iotlcm-public/iotlcm
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
37a1d00f018037a3401c35f1490972675e68fd95
iotlcm/docs/openapi/v3/query.md
T
MiFaZhan 92f239fcc4 chore: 初始开源发布
2026-10-26 15:30:14 +08:00

20 KiB
Raw Blame History

title, description, outline
title description outline
查询类 iotLCM V3 查询类接口 deep

查询类

单卡基本信息查询

POST /openapi/v3/query/sim-info

请求头：

X-Access-Token: {accessToken}

请求体：

字段 类型 说明
appId string 客户组织编码
iccid string ICCID，iccid、msisdn、imsi 至少传一个
msisdn string MSISDN
imsi string IMSI

请求示例：

{
    "appId": "CUS-202601-0001",
    "iccid": "898604F4152391115474"
}

响应结构：

字段 类型 说明
data.iccid string ICCID
data.msisdn string MSISDN
data.imsi string IMSI
data.imei string IMEI
data.username string 当前归属客户/组织名称
data.location string 归属地
data.planCategory string 套餐分类
data.currentPlanName string 当前套餐名称
data.plangroup string 套餐分组，未配置时为空字符串
data.planid string 当前套餐编码
data.appid string 归属客户组织编码
data.allowPlanChange number 是否允许改套餐，未启用时返回 0
data.lastSyncTime string 状态最后同步时间
data.accessType string 接入方式
data.cardStatus string 卡状态
data.cardType any 卡类型
data.networkType any 网络类型
data.activationDate string 出库/激活相关日期
data.activeDate string 当前套餐生效日期
data.validityPeriod number 有效期，按月份计算
data.expiryDate string 当前套餐到期日期
data.testPeriod number 测试期，未启用时返回 0
data.testPeriodExpiryDate any 测试期到期时间，未启用时返回 null
data.silentPeriod number 沉默期，未启用时返回 0
data.silentPeriodExpiryDate any 沉默期到期时间，未启用时返回 null
data.dataService number 数据服务状态，1 启用，0 禁用
data.planData number 套餐总流量，单位 MB
data.usedData number 已用流量，单位 MB
data.remainingData string 剩余流量，单位 MB
data.smsService number 短信服务状态
data.planSMS number 套餐短信总量
data.usedSMS number 已用短信数
data.remainingSMS string 剩余短信数
data.voiceService number 语音服务状态
data.planMinutes number 套餐语音分钟数
data.usedMinutes number 已用语音分钟数
data.remainingMinutes string 剩余语音分钟数
data.internationalRoamingService number 国际漫游服务状态
data.planInternationalData number 国际漫游套餐流量
data.usedInternationalData number 已用国际漫游流量
data.remainingInternationalData string 剩余国际漫游流量
data.description any 备注描述，未填写时返回 null

响应示例：

{
    "code": 0,
    "message": "",
    "data": {
        "iccid": "898604F4152391115474",
        "imei": "",
        "username": "示例企业",
        "location": "370100000000",
        "planCategory": "移动小流量",
        "currentPlanName": "每月100m3年",
        "plangroup": "",
        "planid": "yd-100m-3y",
        "appid": "CUS-202601-0001",
        "allowPlanChange": 0,
        "lastSyncTime": "2026-06-24 00:03:19",
        "accessType": "",
        "cardStatus": "已激活",
        "cardType": "",
        "networkType": "",
        "activationDate": "2026-06-01",
        "activeDate": "2026-06-01",
        "validityPeriod": 32,
        "expiryDate": "2029-01-31",
        "testPeriod": 0,
        "testPeriodExpiryDate": null,
        "silentPeriod": 0,
        "silentPeriodExpiryDate": null,
        "dataService": 1,
        "planData": 100,
        "usedData": 0.875,
        "remainingData": "99.1",
        "smsService": 1,
        "planSMS": 0,
        "usedSMS": 0,
        "remainingSMS": "0",
        "voiceService": 1,
        "planMinutes": 0,
        "usedMinutes": 0,
        "remainingMinutes": "0",
        "internationalRoamingService": 0,
        "planInternationalData": 0,
        "usedInternationalData": 0,
        "remainingInternationalData": "0.0",
        "description": null
    },
    "error": null
}

单卡状态信息查询

POST /openapi/v3/query/sim-status

请求头：

X-Access-Token: {accessToken}

请求体：

字段 类型 说明
appId string token 返回的客户组织编码
iccid string ICCID；与 msisdn、imsi 至少传一个
msisdn string MSISDN
imsi string IMSI

请求示例：

{
    "appId": "CUS-202601-0001",
    "iccid": "898604F4152391115474"
}

响应结构：

字段 类型 说明
code number 业务状态码，成功为 0
message string 错误或提示信息
data.iccid string ICCID，查询命中时返回
data.lifeCycle number 卡生命周期状态编码
data.lifeCycleName string 卡生命周期状态文字
error any 错误信息字段

响应示例（查询命中）：

{
    "code": 0,
    "message": "",
    "data": {
        "iccid": "898604F4152391115474",
        "lifeCycle": 2,
        "lifeCycleName": "已激活"
    },
    "error": null
}

响应示例（未命中）：

{
    "code": 50,
    "message": "查询sim卡信息失败，请确认ICCID，MSISDN，IMSI是否正确",
    "data": {},
    "error": null
}

lifeCycleName 为状态文字；lifeCycle 是此接口的状态编码，不要与其他接口或字典中的状态编码混用。

单卡流量限额查询

POST /openapi/v3/query/sim-limit

请求体：

字段 类型 说明
appId string 客户组织编码
iccid string ICCID
msisdn string MSISDN
imsi string IMSI

请求示例：

{
    "appId": "CUS-202601-0001",
    "iccid": "898604F4152391115474"
}

响应字段：

字段 类型 说明
data.trafficCutoffStatus integer 达量断网状态：0 未配置、1 已开启、2 已关闭
data.trafficCutoffName string 状态名称，返回 未配置、已开启 或 已关闭
data.trafficCutoffThreshold number 达量断网阈值，单位 MB

响应示例：

{
    "code": 0,
    "message": "",
    "data": {
        "trafficCutoffStatus": 1,
        "trafficCutoffName": "已开启",
        "trafficCutoffThreshold": 1024
    },
    "error": null
}

单卡实时终端 IMEI 查询

POST /openapi/v3/query/sim-imei

请求体：

字段 类型 说明
appId string 客户组织编码
iccid string ICCID
msisdn string MSISDN
imsi string IMSI

请求示例：

{
    "appId": "CUS-202601-0001",
    "iccid": "898604F4152391115474"
}

响应结构：

字段 类型 说明
data.imei string IMEI

响应示例：

{
    "code": 0,
    "message": "",
    "data": {
        "imei": ""
    },
    "error": null
}

单卡本月流量使用量查询

POST /openapi/v3/query/sim-usage

请求体：

字段 类型 说明
appId string 客户组织编码
iccid string ICCID
msisdn string MSISDN
imsi string IMSI

请求示例：

{
    "appId": "CUS-202601-0001",
    "iccid": "898604F4152391115474"
}

响应结构：

字段 类型 说明
data.useUnit string 流量单位，固定为 MB
data.useAmount number 当前周期已用流量

响应示例：

{
    "code": 0,
    "message": "",
    "data": {
        "useUnit": "MB",
        "useAmount": 0.875
    },
    "error": null
}

物联网卡批量状态信息查询

POST /openapi/v3/query/sim-status-batch

单次最多查询 1000 张卡。每张卡至少提供 iccid、msisdn、imsi 中的一个；同一条记录提供多个标识时，必须对应同一张卡。

请求头：

X-Access-Token: {accessToken}

请求体：

字段 类型 说明
appId string token 返回的客户组织编码，示例为 CUS-202601-0001
cards array 卡片标识列表；示例包含 3 张卡，单次最多 1000 项
cards[].iccid string ICCID；示例中每项均使用 ICCID，实际调用时与 msisdn、imsi 至少传一个
cards[].msisdn string MSISDN，可代替 ICCID 标识卡片
cards[].imsi string IMSI，可代替 ICCID 标识卡片

请求示例：

{
    "appId": "CUS-202601-0001",
    "cards": [
        {
            "iccid": "898604F4152391115473"
        },
        {
            "iccid": "898604F4152391115474"
        },
        {
            "iccid": "8986112223600594371"
        }
    ]
}

响应结构：

字段 类型 说明
code number 业务状态码，成功为 0
message string 错误或提示信息
data.total integer 本次请求的卡片总数；示例为 3
data.matchedCount integer 匹配成功的卡片数量；示例为 3
data.notFoundCount integer 未匹配成功的卡片数量；示例为 0
data.items array 每张卡的查询结果；示例依次对应请求中的 3 张卡
data.items[].matched boolean 是否匹配成功；示例中均为 true
data.items[].iccid string 匹配成功时返回的 ICCID
data.items[].lifeCycle number 匹配成功时返回的卡生命周期状态编码；示例中 2 为已激活
data.items[].lifeCycleName string 匹配成功时返回的卡生命周期状态文字
data.items[].errorCode string 匹配失败时返回的错误码；示例均匹配成功，因此未返回
data.items[].errorMessage string 匹配失败时返回的错误说明；示例均匹配成功，因此未返回
error any 错误信息字段

响应示例：

{
    "code": 0,
    "message": "",
    "data": {
        "total": 3,
        "matchedCount": 3,
        "notFoundCount": 0,
        "items": [
            {
                "matched": true,
                "iccid": "898604F4152391115473",
                "lifeCycle": 2,
                "lifeCycleName": "已激活"
            },
            {
                "matched": true,
                "iccid": "898604F4152391115474",
                "lifeCycle": 2,
                "lifeCycleName": "已激活"
            },
            {
                "matched": true,
                "iccid": "8986112223600594371",
                "lifeCycle": 2,
                "lifeCycleName": "已激活"
            }
        ]
    },
    "error": null
}

物联网卡批量流量信息查询

POST /openapi/v3/query/sim-usage-batch

单次最多查询 1000 张卡。请求体需传入 appId 和 cards 数组；数组中的每张卡至少提供 iccid、msisdn、imsi 中的一个。同一条记录提供多个标识时，必须对应同一张卡。

请求头：

X-Access-Token: {accessToken}

请求体：

字段 类型 说明
appId string token 返回的客户组织编码
cards array 卡片标识列表，单次最多 1000 项
cards[].iccid string ICCID；每项与 msisdn、imsi 至少传一个
cards[].msisdn string MSISDN，可代替 ICCID 标识卡片
cards[].imsi string IMSI，可代替 ICCID 标识卡片

请求示例：

{
    "appId": "CUS-202601-0001",
    "cards": [
        {
            "iccid": "898604F4152391115474"
        },
        {
            "iccid": "898604F4152391115473"
        },
        {
            "iccid": "8986112223600594371"
        }
    ]
}

响应结构（流量单位为 MB）：

字段 类型 说明
code number 业务状态码，成功为 0
message string 错误或提示信息
data.total integer 本次请求的卡片总数
data.matchedCount integer 匹配成功的卡片数量
data.notFoundCount integer 未匹配成功的卡片数量
data.items array 每张卡的查询结果
data.items[].matched boolean 是否匹配成功
data.items[].iccid string 匹配成功时返回的 ICCID
data.items[].useUnit string 流量单位，示例为 MB
data.items[].useAmount number 流量使用量
data.items[].errorCode string 匹配失败时返回的错误码；匹配成功时不返回
data.items[].errorMessage string 匹配失败时返回的错误说明；匹配成功时不返回
error any 错误信息字段

响应示例：

{
    "code": 0,
    "message": "",
    "data": {
        "total": 3,
        "matchedCount": 3,
        "notFoundCount": 0,
        "items": [
            {
                "matched": true,
                "iccid": "898604F4152391115474",
                "useUnit": "MB",
                "useAmount": 0.875
            },
            {
                "matched": true,
                "iccid": "898604F4152391115473",
                "useUnit": "MB",
                "useAmount": 12.5
            },
            {
                "matched": true,
                "iccid": "8986112223600594371",
                "useUnit": "MB",
                "useAmount": 36.25
            }
        ]
    },
    "error": null
}

物联网卡批量 IMEI 查询

POST /openapi/v3/query/sim-imei-batch

单次最多查询 1000 张卡。每张卡至少提供 iccid、msisdn、imsi 中的一个；同一条记录提供多个标识时，必须对应同一张卡。

请求头：

X-Access-Token: {accessToken}

请求体：

字段 类型 说明
appId string token 返回的客户组织编码
cards array 卡片标识列表，单次最多 1000 项
cards[].iccid string ICCID；每项与 msisdn、imsi 至少传一个
cards[].msisdn string MSISDN，可代替 ICCID 标识卡片
cards[].imsi string IMSI，可代替 ICCID 标识卡片

请求示例：

{
    "appId": "CUS-202601-0001",
    "cards": [
        {
            "iccid": "898604F4152391115474"
        },
        {
            "iccid": "898604F4152391115473"
        },
        {
            "msisdn": "1441543605474"
        }
    ]
}

响应结构：

字段 类型 说明
code number 业务状态码，成功为 0
message string 错误或提示信息
data.total integer 本次请求的卡片总数
data.matchedCount integer 匹配成功的卡片数量
data.notFoundCount integer 未匹配成功的卡片数量
data.items array 每张卡的查询结果，顺序与请求中的 cards 一致
data.items[].matched boolean 是否匹配成功
data.items[].iccid string 匹配成功时返回的 ICCID
data.items[].imei string IMEI；尚未采集到该卡 IMEI 时为空字符串
data.items[].errorCode string 匹配失败时返回的错误码；匹配成功时不返回
data.items[].errorMessage string 匹配失败时返回的错误说明；匹配成功时不返回
error any 错误信息字段

响应示例：

{
    "code": 0,
    "message": "",
    "data": {
        "total": 3,
        "matchedCount": 2,
        "notFoundCount": 1,
        "items": [
            {
                "matched": true,
                "iccid": "898604F4152391115474",
                "imei": ""
            },
            {
                "matched": true,
                "iccid": "898604F4152391115473",
                "imei": "865466070817587"
            },
            {
                "matched": false,
                "imei": "",
                "errorCode": "CARD_NOT_FOUND",
                "errorMessage": "卡片不存在或无权限"
            }
        ]
    },
    "error": null
}

物联网卡批量限额信息查询

POST /openapi/v3/query/traffic-cutoff-config

根据卡片标识批量查询当前达量断网配置。cards[] 中的 iccid、msisdn、imsi 三码至少传一个。

请求体：

字段 类型 说明
appId string 客户组织编码
cards array 卡片标识列表
cards[].iccid string ICCID
cards[].msisdn string MSISDN
cards[].imsi string IMSI
includeUsage boolean 是否返回套餐和流量使用信息

请求示例：

{
    "appId": "CUS-202601-0001",
    "cards": [
        {
            "iccid": "898604F4152391115474"
        },
        {
            "iccid": "898604F4152391115475"
        },
        {
            "iccid": "898604F4152391115476"
        }
    ],
    "includeUsage": true
}

响应结构：

字段 类型 说明
data.total integer 请求中的卡片数量
data.matchedCount integer 匹配成功的卡片数量
data.notFoundCount integer 未匹配成功的卡片数量
data.items array 每张卡的查询结果
data.items[].matched boolean 是否匹配成功
data.items[].iccid string 平台返回的 ICCID
data.items[].trafficCutoffStatus integer 达量断网状态：0 未配置、1 已开启、2 已关闭
data.items[].trafficCutoffStatusName string 达量断网状态名称
data.items[].trafficCutoffThreshold number 达量断网阈值，单位 MB
data.items[].trafficCutoffThresholdUnit string 阈值单位，固定为 MB
data.items[].packageTotalFlowMb number 套餐总流量;includeUsage=true 时返回
data.items[].usedFlowMb number 已用流量;includeUsage=true 时返回
data.items[].remainingFlowMb number 剩余流量;includeUsage=true 时返回
data.items[].errorCode string 匹配失败时返回
data.items[].errorMessage string 匹配失败时返回

响应示例：

以下状态、阈值和流量数值用于展示批量响应结构，实际结果以接口查询为准。

{
    "code": 0,
    "message": "",
    "data": {
        "total": 3,
        "matchedCount": 3,
        "notFoundCount": 0,
        "items": [
            {
                "matched": true,
                "iccid": "898604F4152391115474",
                "trafficCutoffStatus": 0,
                "trafficCutoffStatusName": "未配置",
                "trafficCutoffThreshold": 0,
                "trafficCutoffThresholdUnit": "MB",
                "packageTotalFlowMb": 0,
                "usedFlowMb": 18,
                "remainingFlowMb": 0
            },
            {
                "matched": true,
                "iccid": "898604F4152391115475",
                "trafficCutoffStatus": 1,
                "trafficCutoffStatusName": "已开启",
                "trafficCutoffThreshold": 100,
                "trafficCutoffThresholdUnit": "MB",
                "packageTotalFlowMb": 200,
                "usedFlowMb": 80,
                "remainingFlowMb": 120
            },
            {
                "matched": true,
                "iccid": "898604F4152391115476",
                "trafficCutoffStatus": 2,
                "trafficCutoffStatusName": "已关闭",
                "trafficCutoffThreshold": 50,
                "trafficCutoffThresholdUnit": "MB",
                "packageTotalFlowMb": 100,
                "usedFlowMb": 30,
                "remainingFlowMb": 70
            }
        ]
    },
    "error": null
}

批次状态查询

POST /openapi/v3/query/batch-status

根据指定批次号查询异步处理状态，支持续费、达量断网等异步批次。

请求参数：

字段 类型 说明
appId string 客户组织编码
batchNo string 异步 API 返回的批次号

请求示例：

{
    "appId": "CUS-202601-0001",
    "batchNo": "REN20260910153546001000001"
}

响应结构：

字段 类型 说明
data.batchNo string 请求中的批次号
data.batchAsyncStatus integer 异步状态：0 已创建、1 待处理、2 处理中、3 成功、4 失败、5 部分成功

响应示例：

{
    "code": 0,
    "message": "",
    "data": {
        "batchNo": "REN20260910153546001000001",
        "batchAsyncStatus": 3
    },
    "error": null
}
Reference in New Issue View Git Blame Copy Permalink