文档首页/全球SIM联接 GSL/API参考/API列表/SIM卡管理/查询SIM卡列表 - ListSimCards
更新时间：2025-12-02 GMT+08:00
查看PDF
分享

查询SIM卡列表 - ListSimCards

功能介绍

查询SIM卡列表

调试

您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见权限和授权项。

URI

GET /v1/sim-cards

表1 Query参数

参数

是否必选

参数类型

描述

main_search_type

否

Integer

查询关键标识类型： 1.容器ID(不同类型卡含义如下:ICCID(实体卡)，EID（eSIM）CID（vSIM)) 2.批次号 3.设备IMEI

最小值：0

最大值：99

main_search_key

否

String

查询关键标识值：根据查询关键标识类型进行查询，例如想根据ICCID=xxx进行查询，则main_search_type=1&main_search_key=xxx

最小长度：0

最大长度：128

limit

否

Long

分页查询时每页显示的记录数，默认值为10，取值范围为10-500的整数

最小值：10

最大值：500

缺省值：10

offset

否

Long

分页查询时的页码数，默认值为1，取值范围为1-1000000的整数

最小值：1

最大值：1000000

缺省值：1

sim_status

否

Integer

sim卡状态：

10.可测试

11.未激活

13.可激活

14.已停用

20.在用

30.已拆机

最小值：0

最大值：99

device_status

否

Integer

设备状态: 1.注册 2.重启 3.在线 4.离线

最小值：0

最大值：99

tag_id

否

Array of longs

标签ID，最多支持传10个

数组长度：0 - 10

sim_type

否

Integer

sim卡类型：

1.vSIM

2.eSIM

3.实体卡

最小值：0

最大值：99

order

否

String

排序的顺序，asc表示顺序排序，desc表示倒序排序，不传则默认asc

缺省值：asc

枚举值：

  • asc

  • desc

sort

否

String

排序的属性，目前支持:cid（容器ID）、flow_used（已用流量）、flow_left（剩余流量）、act_date（激活时间）、expire_time（到期时间）

枚举值：

  • cid

  • flow_used

  • flow_left

  • act_date

  • expire_time

msisdn

否

String

MSISDN

最小长度：0

最大长度：32

customer_attribute1

否

String

自定义属性一

最小长度：0

最大长度：100

customer_attribute2

否

String

自定义属性二

最小长度：0

最大长度：100

customer_attribute3

否

String

自定义属性三

最小长度：0

最大长度：100

customer_attribute4

否

String

自定义属性四

最小长度：0

最大长度：100

customer_attribute5

否

String

自定义属性五

最小长度：0

最大长度：100

customer_attribute6

否

String

自定义属性六

最小长度：0

最大长度：100

min_used_flow

否

Long

最小使用流量(MB)

最小值：0

最大值：2147483647

max_used_flow

否

Long

最大使用流量(MB)

最小值：0

最大值：2147483647

min_left_flow

否

Long

最小剩余流量(MB)

最小值：0

最大值：2147483647

max_left_flow

否

Long

最大剩余流量(MB)

最小值：0

最大值：2147483647

real_named

否

Boolean

是否已实名认证: true表示是，false表示否，系统SIM卡实名认证状态非实时。

order_id

否

Long

订单号

最小值：0

最大值：9223372036854774784

filter_downtime_period

否

Boolean

是否过滤停机保号的卡

缺省值：false

order_ids

否

Array of longs

订单批次号集合

price_plan_id

否

Array of strings

套餐id集合，最多支持传30个

pool_flag

否

Integer

流量池标识：0 不使用流量池，1 创建新前向流量池，2 加入已有前向流量池，11 创建新后向流量池，12 加入后向流量池

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

是

String

用户Token。通过调用IAM服务 获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。

响应参数

状态码：200

表3 响应Body参数

参数

参数类型

描述

limit

Long

每页记录数

offset

Long

页码

count

Long

总数

sim_cards

Array of SimDeviceVO objects

sim卡数据集合

表4 SimDeviceVO

参数

参数类型

描述

sim_card_id

Long

sim卡id

account_id

String

账户id

cid

String

容器ID:不同类型卡含义如下 iccid(实体卡)，eid（eSIM）cid（vSIM)

sim_pool_id

Long

流量池ID

imei

String

设备IMEI

sim_status

Integer

sim卡状态：

10.可测试

11.未激活

13.可激活

14.已停用

20.在用

30.已拆机

device_status

Integer

设备状态：1.注册 2.重启 3.在线 4.离线（该参数只有ESIM、VSIM返回，实体卡返回null）

device_model

String

设备模组（该参数只有ESIM、VSIM返回，实体卡返回null）

act_date

String

激活日期 例如2020-01-31T16:00:00.000Z

device_status_date

String

设备状态变更时间 例如2020-01-31T16:00:00.000Z（该参数只有ESIM、VSIM返回，实体卡返回null）

node_id

String

设备标识

iccid

String

码号iccid

network_type

String

网络类型

dbm

String

信号强度（该参数只有ESIM、VSIM返回，实体卡返回null）

signal_level

String

信号等级:1.差 2.良 3.优（该参数只有ESIM、VSIM返回，实体卡返回null）

sim_type

Integer

sim卡类型 1.vSIM 2.eSIM 3.实体卡

tag_names

String

标签名

order_id

Long

批次号

expire_time

String

到期时间 例如2021-06-30T00:00:00.000Z

price_plan_name

String

在用套餐名

最大长度：128

sim_price_plan_id

Long

套餐订购实例ID

flow_left

Double

剩余流量(单位M)，数据默认截止到昨日24点。

flow_used

Double

已用流量(单位M)，数据默认截止到昨日24点。

operator_status

Integer

停机类型 -1.正常（非停机状态） 1.停机（超流量停机） 2.停机（超流量阈值停机） 3.停机（流量池停机） 4.停机（套餐到期停机） 5.停机（主动停机） 6.停机（违规停机） 7.停机（机卡分离停机）

msisdn

String

MSISDN

最大长度：32

imsi

String

IMSI

最大长度：32

customer_attribute1

String

自定义属性一

最大长度：100

customer_attribute2

String

自定义属性二

最大长度：100

customer_attribute3

String

自定义属性三

最大长度：100

customer_attribute4

String

自定义属性四

最大长度：100

customer_attribute5

String

自定义属性五

最大长度：100

customer_attribute6

String

自定义属性六

最大长度：100

real_named

Boolean

是否已实名认证: true表示是，false表示否，系统SIM卡实名认证状态非实时。

cut_net_flag

Boolean

是否单独断网 true:断网，false:未断网 （当前只支持联通、移动的组池卡，电信卡不限制）

exceed_cut_net_flag

Boolean

是否达量断网 true:达量断网，false:未达量断网 （当前只支持联通、移动的组池卡，电信卡不限制）

exceed_cut_net_quota

Integer

达量断网阈值（单位MB 当前仅电信卡支持）

imei_bind_remain_times

Integer

本月机卡绑定剩余次数（当前仅电信卡支持）

speed_value

Integer

网络限制速率（单位Kbps,当前电信联通卡支持）

状态码：400

表5 响应Body参数

参数

参数类型

描述

error_code

String

错误码

error_msg

String

错误描述

状态码：403

表6 响应Body参数

参数

参数类型

描述

error_code

String

错误码

error_msg

String

错误描述

状态码：500

表7 响应Body参数

参数

参数类型

描述

error_code

String

错误码

error_msg

String

错误描述

请求示例

查询公有云租户下的SIM卡列表，每页返回10条数据，从第1页开始。

GET https://{endpoint}/v1/sim-cards?offset=1&limit=10

响应示例

状态码：200

OK

{
  "limit" : 10,
  "offset" : 1,
  "count" : 1,
  "sim_cards" : [ {
    "sim_card_id" : 4900000000000,
    "account_id" : "04eef84xxxxxxxxxxx",
    "cid" : "8986xxxxxxxxxx",
    "sim_pool_id" : 4940000000,
    "imei" : null,
    "sim_status" : 14,
    "device_status" : null,
    "device_model" : null,
    "act_date" : "2022-09-16T01:14:58.000+00:00",
    "device_status_date" : null,
    "node_id" : null,
    "iccid" : "8986xxxxxxxxxxx",
    "network_type" : null,
    "dbm" : null,
    "signal_level" : null,
    "sim_type" : 3,
    "tag_names" : null,
    "order_id" : 494000000000,
    "expire_time" : "2023-08-26T15:59:59.000+00:00",
    "price_plan_name" : "中国联通消费级每月30M联接服务（1年）",
    "sim_price_plan_id" : null,
    "flow_left" : 30,
    "flow_used" : 0,
    "operator_status" : 5,
    "msisdn" : "86xxxxxxxxx",
    "imsi" : "46xxxxxxxxxx",
    "customer_attribute1" : null,
    "customer_attribute2" : null,
    "customer_attribute3" : null,
    "customer_attribute4" : null,
    "customer_attribute5" : null,
    "customer_attribute6" : null,
    "real_named" : false,
    "cut_net_flag" : false,
    "exceed_cut_net_flag" : false,
    "exceed_cut_net_quota" : null,
    "imei_bind_remain_times" : null,
    "speed_value" : null
  } ]
}

状态码：400

Parameter Invalid

{
  "error_code" : "GSL.00010004",
  "error_msg" : "参数异常"
}

状态码：403

Forbidden

{
  "error_code" : "GSL.00016016",
  "error_msg" : "5分钟内不允许重复操作，请稍作等待。"
}

状态码：500

Internal Server Error

{
  "error_code" : "GSL.00010003",
  "error_msg" : "系统繁忙，请稍后重试。"
}

状态码

状态码

描述

200

OK

400

Parameter Invalid

403

Forbidden

500

Internal Server Error

错误码

请参见错误码。

父主题：SIM卡管理

相关文档