iotlcm-public/iotlcm
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: 初始开源发布

Browse Source
This commit is contained in:
MiFaZhan
2026-10-22 15:16:43 +08:00
commit 92f239fcc4
114 changed files with 8018 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/openapi/index.md
+23
View File
@@ -0,0 +1,23 @@
---
layout: home
hero:
name: iotLCM OpenAPI
text: 接口文档
tagline: 对接说明：鉴权方式、请求参数、响应结构与示例。
actions:
- theme: brand
text: V3 接口（推荐）
link: /openapi/v3/
- theme: alt
text: 旧版兼容接口
link: /openapi/legacy/
features:
- title: 版本选型指引
details: 新接入推荐使用 V3。V3 接口位于 /openapi/v3/query，通过 X-Access-Token 鉴权，调用时需在请求体中传入 token 接口返回的 appId（⚠️ 注意区分：appKey 用于获取 token，appId 由 token 接口返回并在后续调用中传入），数据权限按账号所属客户隔离；旧版兼容接口位于 /route/open，通过请求 body verify 入参鉴权，仅作为存量客户兼容保留。
- title: V3 接口
details: 鉴权、获取客户调用凭证、查询 SIM 卡信息、查询 SIM 流量限制、查询 SIM IMEI（单卡 / 批量）、查询 SIM 流量用量。
- title: 旧版兼容接口
details: 查询 SIM 详情、查询 SIM 账期用量、查询 SIM 历史月用量、查询 SIM 状态、查询 SIM 在线会话、查询卡列表信息。
---
docs/openapi/legacy/index.md
+133
View File
@@ -0,0 +1,133 @@
---
title: 概览与鉴权
description: iotLCM 旧版兼容接口概览与鉴权说明
outline: deep
---
# 概览与鉴权
本文档收录历史 `/route/open/*` 路径下仍在维护的兼容接口。鉴权通过请求体 `verify` 中的 `appId`、`password` 和 `timeStamp` 完成；`sign` 为历史兼容字段，当前服务不校验。
这些接口由 iotLCM OpenAPI 服务实现并提供，与 V3 接口同域（`api.iotlcm.example.com`），仅请求路径与鉴权方式不同。
## 服务地址
```text
https://api.iotlcm.example.com
```
完整请求 URL：
```text
https://api.iotlcm.example.com/route/open/{接口名}
```
## 统一鉴权
以下各接口的“请求示例”均为完整 JSON 请求体，调用时请设置 `Content-Type: application/json`；`verify.sign` 可传空字符串 `""`。
所有接口通过请求体 `verify` 字段鉴权：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| appId | string | 用于唯一标识请求 |
| password | string | 密码 |
| timeStamp | string | 时间戳，`"" + System.currentTimeMillis()` |
| sign | string | 当前服务不校验，可传空字符串 `""`。 |
### 历史签名规则（仅供参考）
当前服务不要求计算签名，也无需提供 `accessKey`。以下为历史客户端示例中的签名算法，仅供维护已有签名逻辑时参考。
```text
appId={appId}&password={password}&timeStamp={timeStamp}&key={accessKey}
```
对拼接后的字符串计算 MD5，并将结果转为大写，即为 `sign`。`sign` 不参与签名计算；`accessKey` 仅用于签名，不放入请求体的 `verify` 字段。
## 统一返回结构
```json
{
"status": 0,
"message": "",
"result": {}
}
```
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| status | number | 业务状态码，成功为 `0` |
| message | string | 错误或提示信息 |
| result | any | 业务数据 |
## 公共字典
卡状态编码（适用于 `cardInfo`、`simStatus`、`queryCardInfoList` 响应中的 `statusId` / `statusCode` / `status`）：
| 编码 | 说明 |
| --- | --- |
| 1 | 库存 |
| 2 | 可测试 |
| 3 | 待激活 |
| 4 | 已激活 |
| 5 | 已停机 |
| 6 | 预销户 |
| 7 | 已销户 |
| 8 | 未知 |
## 请求案例
以下为历史 Java 示例，保留原有 `verify` 块与 `sign` 的生成方式供参考。调用当前服务时，可直接设置 `verify.sign` 为 `""`，省略签名计算。
```java
// 服务器请求地址
protected static String server_Ip = "https://api.iotlcm.example.com/route/open";
// appId
public static String appId = null;
// 密钥密码
public static String password = null;
/**
* Sign 加密类
*/
public static String getSign(Map<String, Object> map, String key) {
List<String> list = new ArrayList<>(map.keySet());
Collections.sort(list);
StringBuffer sb = new StringBuffer();
for (int i = 0; i < list.size(); i++) {
String k = list.get(i);
String v = (String) map.get(k);
sb.append(k).append("=").append(v).append("&");
}
String signstr = sb.append("key=").append(key).toString();
String sign = MD5Util.MD5Encode(signstr).toUpperCase();
return sign;
}
public static void main(String[] args) {
Map<String, Object> map = new HashMap<>();
Map<String, Object> parmap = new HashMap<>();
Map<String, Object> verify = new HashMap<>();
String appId = "test";
String password = "uhbhkh223123";
String accessKey = "1234567896132";
String timeStamp = "" + System.currentTimeMillis();
verify.put("password", password);
verify.put("appId", appId);
verify.put("timeStamp", timeStamp);
verify.put("sign", getSign(verify, accessKey));
parmap.put("type", "iccid");
parmap.put("cardno", "89860423123123132135");
map.put("verify", verify);
map.put("Param", parmap);
server_Ip += "/cardInfo";
String result = HttpUtil.post(server_Ip, JSON.toJSONString(map));
System.out.println(result);
}
```
docs/openapi/legacy/query.md
+389
View File
@@ -0,0 +1,389 @@
---
title: 查询类
description: iotLCM 旧版兼容查询类接口
outline: deep
---
# 查询类
## 查询 SIM 详情
```http
POST /route/open/cardInfo
```
简要描述：查询物联卡基础信息。
请求体：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| type | string | 查询类型：`msisdn` / `iccid` / `imsi` / `vid` |
| cardno | string | 对应的查询值 |
请求示例：
```json
{
"Param": {
"type": "iccid",
"cardno": "898604F4152391115474"
},
"verify": {
"timeStamp": "1784097284347",
"password": "YOUR_APP_SECRETebdebae9763127943f097758e029a0fdbc",
"appId": "YOUR_APP_ID",
"sign": ""
}
}
```
响应结构：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| vid | string | 本地卡记录 ID |
| msisdn | string | MSISDN |
| iccid | string | ICCID |
| imsi | string | IMSI |
| imei | string | IMEI |
| deptName | string | 当前归属组织名称 |
| statusId | number | 状态编码，参考公共字典 |
| packageId | string | 当前套餐编码 |
| packageName | string | 当前套餐名称 |
| used | number | 当前周期已用流量，单位 MB |
| remaining | number | 当前周期剩余流量，单位 MB |
| type | string | 卡类型名称 |
| packetArr | array | 资费计划，未配置时返回 `null` |
| remark | string | 备注 |
| grouping | string | 分组，未配置时为空字符串 |
| deliverDate | string | 发货日期，未配置时为空字符串 |
| activateDate | string | 激活日期 |
| expireTime | string | 到期时间 |
响应示例：
```json
{
"status": 0,
"message": "",
"result": {
"vid": "3933",
"msisdn": "1441543605474",
"iccid": "898604F4152391115474",
"imsi": "460087436015474",
"imei": "",
"deptName": "示例企业",
"statusId": 4,
"packageId": "yd-100m-3y",
"packageName": "每月100m3年",
"used": 0.875,
"remaining": 99.125,
"type": "",
"packetArr": null,
"remark": "测试卡",
"grouping": "",
"deliverDate": "",
"activateDate": "2026-06-01",
"expireTime": "2029-01-31 23:59:59"
}
}
```
## 查询 SIM 账期用量
```http
POST /route/open/simDataUsage
```
请求体：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| iccid | string | ICCID |
请求示例：
```json
{
"Param": {
"iccid": "898604F4152391115474"
},
"verify": {
"timeStamp": "1784097284347",
"password": "YOUR_APP_SECRETebdebae9763127943f097758e029a0fdbc",
"appId": "YOUR_APP_ID",
"sign": ""
}
}
```
响应结构：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| useUnit | string | 单位，当前为 `MB` |
| useAmount | number | 当前周期已用流量 |
响应示例：
```json
{
"status": 0,
"message": "",
"result": {
"useUnit": "MB",
"useAmount": 0.875
}
}
```
## 查询 SIM 历史月用量
```http
POST /route/open/simDataUsageMonthly
```
请求体：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| iccid | string | ICCID |
| dateTime | string | 查询月份，格式 `yyyyMM`（示例：`202509`） |
请求示例：
```json
{
"Param": {
"iccid": "898604F4152391115474",
"dateTime": "202509"
},
"verify": {
"timeStamp": "1784097284347",
"password": "YOUR_APP_SECRETebdebae9763127943f097758e029a0fdbc",
"appId": "YOUR_APP_ID",
"sign": ""
}
}
```
响应结构：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| useUnit | string | 单位，当前为 `MB` |
| useAmount | number | 指定月份用量 |
响应示例：
```json
{
"status": 0,
"message": "",
"result": {
"useUnit": "MB",
"useAmount": 0
}
}
```
## 查询 SIM 状态
```http
POST /route/open/simStatus
```
请求体：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| iccid | string | ICCID |
请求示例：
```json
{
"Param": {
"iccid": "898604F4152391115474"
},
"verify": {
"timeStamp": "1784097284347",
"password": "YOUR_APP_SECRETebdebae9763127943f097758e029a0fdbc",
"appId": "YOUR_APP_ID",
"sign": ""
}
}
```
响应结构：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| statusMessage | string | 状态描述 |
| statusCode | number | 状态编码，参考公共字典 |
响应示例：
```json
{
"status": 0,
"message": "",
"result": {
"statusMessage": "已激活",
"statusCode": 4
}
}
```
## 查询 SIM 在线会话
```http
POST /route/open/simSession
```
请求体：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| iccid | string | ICCID |
请求示例：
```json
{
"Param": {
"iccid": "898604F4152391115474"
},
"verify": {
"timeStamp": "1784097284347",
"password": "YOUR_APP_SECRETebdebae9763127943f097758e029a0fdbc",
"appId": "YOUR_APP_ID",
"sign": ""
}
}
```
响应结构：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| typeName | string | 运营商系统类型，未上报时为空字符串 |
| imei | string | IMEI，未上报时为空字符串 |
| statusMessage | string | 状态描述，未上报时为空字符串 |
| statusCode | number | 状态码，未上报时为 `0` |
| data | object | 会话详情 |
`data` 字段：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| apnId | string | APN ID |
| rat | string | 接入方式 |
| ipv6 | string | IPv6 地址 |
| ip | string | IPv4 地址 |
| ipv6Prefix | string | IPv6 前缀 |
| status | string | 在线状态 |
| createDate | string | 会话创建时间 |
响应示例：
```json
{
"status": 0,
"message": "",
"result": {
"typeName": "",
"imei": "",
"statusMessage": "",
"statusCode": 0,
"data": {
"apnId": "",
"rat": "",
"ipv6": "",
"ip": "",
"ipv6Prefix": "",
"status": "",
"createDate": ""
}
}
}
```
## 查询卡列表信息
```http
POST /route/open/queryCardInfoList
```
请求体：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| iccid | `array<string>` | ICCID 列表，最多支持 100 个 |
请求示例：
```json
{
"Param": {
"iccid": [
"898604F4152391115473",
"898604F4152391115474"
]
},
"verify": {
"timeStamp": "1784097284347",
"password": "YOUR_APP_SECRETebdebae9763127943f097758e029a0fdbc",
"appId": "YOUR_APP_ID",
"sign": ""
}
}
```
响应结构：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| iccid | string | ICCID |
| activateDate | string | 激活日期 |
| dueExpireTime | string | 到期时间 |
| imei | string | IMEI |
| imsi | string | IMSI |
| msisdn | string | MSISDN |
| type | string | 卡类型 |
| remarks | string | 备注 |
| status | number | 状态编码，参考公共字典 |
响应示例：
```json
{
"status": 0,
"message": "",
"result": [
{
"iccid": "898604F4152391115473",
"activateDate": "2023-05-11",
"dueExpireTime": "",
"imei": "",
"imsi": "460087436015473",
"msisdn": "1441543605473",
"type": "",
"remarks": "测试卡",
"status": 4
},
{
"iccid": "898604F4152391115474",
"activateDate": "2026-06-01",
"dueExpireTime": "2029-01-31 23:59:59",
"imei": "",
"imsi": "460087436015474",
"msisdn": "1441543605474",
"type": "",
"remarks": "测试卡",
"status": 4
}
]
}
```
docs/openapi/operator/index.md
+14
View File
@@ -0,0 +1,14 @@
---
title: 共享 Token 接口概览
description: 共享 Token 接口与白名单转发说明
outline: deep
---
# 共享 Token 接口概览
本目录包含共享 Token 获取接口和白名单转发说明。
## 接口文档
- [共享 Token 接口](./shared-token/)
- [白名单转发](./mobile-v5/)
docs/openapi/operator/mobile-v5/index.md
+138
View File
@@ -0,0 +1,138 @@
---
title: 白名单转发
description: 通过 api.iotlcm.example.com 访问中国移动物联网能力开放平台 V5 接口
outline: deep
---
# 白名单转发
本目录说明如何通过 `api.iotlcm.example.com` 访问中国移动物联网能力开放平台 V5 接口。平台仅提供安全代理转发，不改变中国移动 V5 接口的请求方法、请求参数、响应结构和业务语义。
## 服务地址
客户侧统一使用：
```text
https://api.iotlcm.example.com
```
V5 接口的请求路径保持与中国移动官方接口一致，将官方域名替换为平台域名即可：
```text
https://api.iotlcm.example.com/v5/{官方接口路径}
```
例如，官方接口路径为 `/v5/ec/query/sim-basic-info` 时，客户侧请求路径为：
```http
POST https://api.iotlcm.example.com/v5/ec/query/sim-basic-info
```
平台会将该请求转发至：
```text
https://api.iot.10086.cn/v5/ec/query/sim-basic-info
```
> [!IMPORTANT] 使用 POST 时务必携带 JSON 请求体
> 中国移动 V5 接口对 `POST` 只接受 JSON 格式。通过代理请求时必须设置
> `Content-Type: application/json`，并在请求体中传入参数；
> 未带该请求头或使用表单编码（`application/x-www-form-urlencoded`）会返回
> `{"status":"11012","message":"POST请求仅支持JSON格式","result":[]}`。
>
> 若使用 `GET`，则以 Query 参数传参，无需设置 `Content-Type`。
## 调用前准备
调用 V5 业务接口前，需要先从平台取得以下信息：
| 参数 | 说明 |
| --- | --- |
| `appid` | 第三方应用唯一标识 |
| `password` | 应用密钥 |
| `transid` | 按官方规则生成的事务编码 |
| `token` | 通过共享 Token 接口获取的运营商令牌 |
其中 `transid` 由客户生成，通常遵循 `appid + YYYYMMDDHHMISS + 8位数字序列`；中国移动通常不校验此事务编号。具体规则及字段约束以中国移动当前发布的接口文档为准。
## 业务接口示例
以下接口字段摘自中国移动 V5 接口清单，用于说明代理路径的写法。完整接口、字段、错误码和版本变更请以官方文档为准。
### 单卡基本信息查询
```http
POST https://api.iotlcm.example.com/v5/ec/query/sim-basic-info
```
请求参数：
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `transid` | string | 事务编码 |
| `token` | string | V5 Token |
| `msisdn` | string | 物联卡号码 |
| `iccid` | string | ICCID；与 `msisdn`、`imsi` 按官方规则选择 |
| `imsi` | string | IMSI |
请求示例：
```json
{
"transid": "YOUR_TRANSID",
"token": "YOUR_ACCESS_TOKENf3515b3bdaeca904dd2e904061b65e8153",
"iccid": "898608501624D0000009"
}
```
响应主要字段：
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `status` | string | `0` 表示成功，非 `0` 表示失败 |
| `message` | string | 错误或提示信息 |
| `result` | array | 查询结果 |
| `result[].msisdn` | string | 物联卡号码 |
| `result[].iccid` | string | ICCID |
| `result[].imsi` | string | IMSI |
| `result[].activeDate` | string | 首次激活日期 |
| `result[].openDate` | string | 开卡时间 |
响应示例：
```json
{
"status": "0",
"message": "正确",
"result": [
{
"msisdn": "1442206200009",
"imsi": "460240406200009",
"iccid": "898608501624D0000009",
"activeDate": "2025-03-26 15:49:50",
"openDate": "2025-03-13 16:52:10",
"remark": ""
}
]
}
```
## 请求与响应约定
- V5 接口支持的请求方法、参数位置（Query 或 Form）、参数格式和字段大小写均以中国移动官方文档为准。
- `GET` 与 `POST` 均可通过本代理访问。使用 `POST` 时**必须**设置 `Content-Type: application/json` 并携带 JSON 请求体，否则返回 `11012`；使用表单编码亦不被接受。
- 代理会以平台固定出口地址访问中国移动，因此客户端侧的来源 IP 无需加入中国移动白名单；请勿在请求中自行添加 `X-Forwarded-For`、`X-Real-IP` 等来源标识请求头，中国移动会依据其判定 IP 鉴权，携带非白名单地址将返回 `12003`。
- 平台不将 V5 响应包装成 iotLCM V3 的 `code/message/data` 结构，客户应直接按照中国移动 V5 响应结构解析。
- 运营商 Token 具有有效期，收到 Token 失效类错误后应重新获取，不建议长期缓存。
## 官方资料
接口完整清单、参数定义、返回示例、错误码和 SDK 示例请参阅：
[中国移动物联网能力开放平台 V5 接口文档下载页面](https://api.iot.10086.cn/api/index.html#/resourceCenter/docDownload)
平台代理入口仅替换访问域名，不替代中国移动官方接口规范。
docs/openapi/operator/shared-token/index.md
+87
View File
@@ -0,0 +1,87 @@
---
title: 共享 Token 接口
description: 共享 Token 接口说明
outline: deep
---
# 共享 Token 接口
本接口用于获取平台已开放共享权限的移动运营商访问 Token。客户无需直接维护运营商应用密钥，平台根据客户已授权的通道配置完成校验并向运营商申请 Token。
## 服务地址
```text
https://api.iotlcm.example.com
```
HTTP（`http://api.iotlcm.example.com`）仅为存量兼容保留，不做自动跳转，新接入请使用 HTTPS。
## 接口信息
```http
POST /openapi/v3/query/operator-token
```
请求头：`Content-Type: application/json`。
请求体：
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `appId` | string | 平台分配的客户应用标识 |
| `chanKey` | string | 已开通共享 Token 权限的通道标识 |
请求示例：
```json
{
"appId": "7s9g2p5n8z1d4m6r",
"chanKey": "channel_010"
}
```
响应中的 `data.accessToken` 用于调用移动运营商 V5 接口。Token 的有效期以 `data.tokenExpire` 为准，请勿将 Token 写入代码仓库或日志。
响应示例：
失败时，接口返回的 `data` 为 `{}`，不是 `null`；例如 `code=50` 表示平台侧获取运营商 Token 失败。
```json
{
"code": 0,
"message": "",
"data": {
"chanAlias": "中国移动物联网",
"chanKey": "channel_010",
"accessToken": "YOUR_ACCESS_TOKENf3515b3bdaeca904dd2e904061b65e8153",
"tokenExpire": "2026-09-09 16:00:00"
},
"error": null
}
```
## 字段说明
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `code` | number | 平台业务状态码，`0` 表示成功；`50` 表示平台侧获取运营商 Token 失败 |
| `message` | string | 错误或提示信息 |
| `data` | object | 成功时返回 Token 信息；失败时返回空对象 `{}`，不是 `null` |
| `data.chanAlias` | string | 通道名称 |
| `data.chanKey` | string | 通道标识 |
| `data.accessToken` | string | 移动运营商接口访问 Token |
| `data.tokenExpire` | string | Token 过期时间 |
| `error` | any | 错误详情；无错误时通常为 `null` |
## 调用示例
```bash
curl --request POST \
--url https://api.iotlcm.example.com/openapi/v3/query/operator-token \
--header 'Content-Type: application/json' \
--data '{
"appId": "7s9g2p5n8z1d4m6r",
"chanKey": "channel_010"
}'
```
共享 Token 仅适用于已开通共享权限的通道。若通道未授权、客户应用标识与通道不匹配，或运营商 Token 获取失败，接口将返回失败信息。
docs/openapi/shared-operator-token.md
+10
View File
@@ -0,0 +1,10 @@
---
title: 共享 Token 接口
description: 共享 Token 接口文档兼容入口
sidebar: false
search: false
---
# 共享 Token 接口
文档已归档到运营商接口模块，请访问[共享 Token 接口](./operator/shared-token/)。
docs/openapi/v3/common.md
+344
View File
@@ -0,0 +1,344 @@
---
title: 业务类
description: iotLCM V3 业务类接口
outline: deep
---
# 业务类
## 服务地址
```text
https://api.iotlcm.example.com
```
HTTP（`http://api.iotlcm.example.com`）仅为存量兼容保留，不做自动跳转，新接入请使用 HTTPS。
## 鉴权
先调用 `/openapi/v3/query/token` 获取访问令牌，再在请求头中传入 `X-Access-Token`。请求体中的 `appId` 必须与凭证所属客户一致。
## 统一返回结构
```json
{
"code": 0,
"message": "",
"data": {},
"error": null
}
```
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | number | 业务状态码，成功为 `0` |
| `message` | string | 错误或提示信息 |
| `data` | object | 业务数据 |
| `error` | any | 错误详情 |
## 单卡套餐续费
```http
POST /openapi/v3/change/sim-subscribe
```
单卡续费按串行方式执行，接口等待本卡处理完成后直接返回结果。
请求参数：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `appId` | string | 客户组织编码 |
| `iccid` | string | ICCID |
| `msisdn` | string | MSISDN/卡号 |
| `imsi` | string | IMSI |
| `packageId` | string | 目标套餐编码 |
| `validity` | integer | 续费时长，单位为年，最小值为 `1` |
| `remark` | string | 续费备注 |
> `iccid`、`msisdn`、`imsi` 至少传一个。
请求示例：
```json
{
"appId": "CUS-202608-0001",
"iccid": "89860401785462635152",
"packageId": "001",
"validity": 1,
"remark": "客户单卡续费"
}
```
响应字段：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `orderId` | string | 订单 ID |
| `orderSn` | string | 订单号 |
| `iccid` | string | 续费卡 ICCID |
| `planName` | string | 续费套餐名称 |
| `effectiveType` | string | 生效类型 |
| `effectiveDate` | string | 套餐生效日期 |
| `expireDate` | string | 套餐到期日期 |
| `amount` | number | 续费金额 |
| `status` | string | 续费状态，成功为 `success`，失败为 `failed` |
| `errorCode` | string | 失败时返回的错误编码 |
| `errorMessage` | string | 失败时返回的错误说明 |
响应示例：
```json
{
"code": 0,
"message": "",
"data": {
"orderId": "54",
"orderSn": "REN20260910153546001000001",
"iccid": "89860401785462635152",
"planName": "中移-1G",
"effectiveType": "immediate",
"effectiveDate": "2026-09-10 15:35:46",
"expireDate": "2027-09-10 15:35:46",
"amount": 0,
"status": "success"
},
"error": null
}
```
失败时仍按统一返回结构返回 `data`，并通过 `status=failed` 和 `errorMessage` 说明失败原因。
```json
{
"code": 0,
"message": "",
"data": {
"orderId": "0",
"orderSn": "",
"iccid": "89860401785462635152",
"planName": "",
"effectiveType": "",
"effectiveDate": "",
"expireDate": "",
"amount": 0,
"status": "failed",
"errorCode": "RENEW_FAILED",
"errorMessage": "卡片不存在或无权限"
},
"error": null
}
```
## 单卡限额变更
```http
POST /openapi/v3/change/sim-traffic-cutoff
```
单卡配置按串行方式执行，接口等待本卡处理完成后直接返回配置结果。
请求参数：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `appId` | string | 客户组织编码 |
| `iccid` | string | ICCID |
| `msisdn` | string | MSISDN/卡号 |
| `imsi` | string | IMSI |
| `trafficCutoffStatus` | integer | `0` 删除，`1` 开启，`2` 关闭 |
| `trafficCutoffThreshold` | number | 达量阈值，单位为 MB；开启时必须大于 `0` |
| `remark` | string | 配置备注 |
> `iccid`、`msisdn`、`imsi` 三码至少传一个。trafficCutoffStatus=0 表示取消达量断网配置。
请求示例：
```json
{
"appId": "CUS-202608-0001",
"iccid": "89860401785462635152",
"trafficCutoffStatus": 1,
"trafficCutoffThreshold": 1024,
"remark": "客户开启达量断网"
}
```
响应字段：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `success` | boolean | 是否配置成功 |
| `iccid` | string | 平台卡 ICCID |
| `msisdn` | string | MSISDN |
| `imsi` | string | IMSI |
| `trafficCutoffStatus` | integer | `0` 删除，`1` 已开启，`2` 已关闭 |
| `trafficCutoffThreshold` | number | 达量阈值，单位为 MB |
| `trafficCutoffThresholdUnit` | string | 阈值单位，固定为 `MB` |
| `message` | string | 处理结果说明 |
| `errorCode` | string | 失败时的错误编码 |
响应示例：
```json
{
"code": 0,
"message": "",
"data": {
"success": true,
"iccid": "89860401785462635152",
"msisdn": "141****5152",
"imsi": "460045462635152",
"trafficCutoffStatus": 1,
"trafficCutoffThreshold": 1024,
"trafficCutoffThresholdUnit": "MB",
"message": "traffic cutoff configuration succeeded"
},
"error": null
}
```
失败时仍返回同一响应结构，`success=false`，`message` 为失败原因。
```json
{
"code": 0,
"message": "",
"data": {
"success": false,
"iccid": "89860401785462635152",
"trafficCutoffStatus": 1,
"trafficCutoffThreshold": 1024,
"trafficCutoffThresholdUnit": "MB",
"message": "卡片不存在或无权限",
"errorCode": "TRAFFIC_CUTOFF_FAILED"
},
"error": null
}
```
## 物联网卡批量套餐续费
```http
POST /openapi/v3/change/batch-sim-subscribe
```
批量续费只创建异步批次，不等待所有卡执行完成。请保存响应中的 `batchNo`，再通过批次查询接口跟踪处理结果。
批量接口提交成功后只返回批次信息；卡片执行成功或失败请通过批次查询接口获取。
请求参数：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `appId` | string | 客户组织编码 |
| `cards` | array | 续费卡列表 |
| `cards[].iccid` | string | ICCID |
| `cards[].msisdn` | string | MSISDN/卡号 |
| `cards[].imsi` | string | IMSI |
| `packageId` | string | 目标套餐编码 |
| `validity` | integer | 续费时长，单位为年 |
| `remark` | string | 续费备注 |
> 每个 `cards[]` 明细中的`iccid`、`msisdn`、`imsi` 三码至少传一个。
请求示例：
```json
{
"appId": "CUS-202608-0001",
"cards": [
{
"iccid": "89860401785462635152"
}
],
"packageId": "001",
"validity": 1,
"remark": "客户批量续费"
}
```
响应字段：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `batchNo` | string | 系统生成的续费批次号 |
| `batchType` | integer | 批次类型，续费为 `101` |
| `total` | integer | 提交的卡数量 |
响应示例：
```json
{
"code": 0,
"message": "",
"data": {
"batchNo": "REN20260910153546001000002",
"batchType": 101,
"total": 1
},
"error": null
}
```
## 物联网卡批量限额变更
```http
POST /openapi/v3/change/batch-sim-traffic-cutoff
```
批量配置只创建异步批次，不等待所有卡执行完成。请保存响应中的 `batchNo`，再通过批次查询接口跟踪处理结果。
批量接口提交成功后只返回批次信息；卡片执行成功或失败请通过批次查询接口获取。
请求参数：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `appId` | string | 客户组织编码 |
| `cards` | array | 配置卡列表，单次最多 1000 张 |
| `cards[].iccid` | string | ICCID |
| `cards[].msisdn` | string | MSISDN/卡号 |
| `cards[].imsi` | string | IMSI |
| `trafficCutoffStatus` | integer | `0` 删除，`1` 开启，`2` 关闭 |
| `trafficCutoffThreshold` | number | 达量阈值，单位为 MB；开启时必须大于 `0` |
| `remark` | string | 配置批次备注 |
> 每个 `cards[]` 明细中的`iccid`、`msisdn`、`imsi` 三码至少传一个。`trafficCutoffStatus=0`时表示取消达量断网配置。
请求示例：
```json
{
"appId": "CUS-202608-0001",
"cards": [
{
"iccid": "89860401785462635152"
}
],
"trafficCutoffStatus": 1,
"trafficCutoffThreshold": 1024,
"remark": "客户批量开启达量断网"
}
```
响应字段：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `batchNo` | string | 系统生成的达量断网配置批次号 |
| `batchType` | integer | 批次类型，达量断网配置为 `41` |
响应示例：
```json
{
"code": 0,
"message": "",
"data": {
"batchNo": "TCC20260910153546001000001",
"batchType": 41
},
"error": null
}
```
docs/openapi/v3/index.md
+79
View File
@@ -0,0 +1,79 @@
---
title: 概览与鉴权
description: iotLCM V3 接口概览与鉴权说明
outline: deep
---
# 概览与鉴权
## 服务地址
```text
https://api.iotlcm.example.com
```
HTTP（`http://api.iotlcm.example.com`）仅为存量兼容保留，不做自动跳转，新接入请使用 HTTPS。
## 统一返回结构
V3 返回格式：
```json
{
"code": 0,
"message": "",
"data": {},
"error": null
}
```
字段说明：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| code | number | 业务状态码，成功为 `0` |
| message | string | 错误或提示信息 |
| data | object | 业务数据 |
| error | any | 错误信息字段 |
## 公共字典
卡状态编码
| 编码 | 说明 |
| :-: | :-: |
| 0 | 未知 |
| 1 | 待激活 |
| 2 | 已激活 |
| 4 | 停机 |
| 6 | 可测试 |
| 7 | 库存 |
| 8 | 预销户 |
| 9 | 已销户 |
## V3 鉴权
V3 路由前缀：
```text
/openapi/v3/query
/openapi/v3/change
```
文档中的“请求示例”仅展示请求 body；调用 V3 POST 接口时，请设置 `Content-Type: application/json` 并将示例 JSON 作为请求体发送。请求路径和鉴权请求头见各接口说明。
除获取 token 接口外，其他 V3 接口需要请求头：
```http
X-Access-Token: {accessToken}
```
也支持传入带 `Bearer ` 前缀的值，服务端会去掉前缀。
::: info 重要：请求体中的 appId 必须正确
先调用 `/openapi/v3/query/token` 获取 token，接口响应中会返回 `data.appId`（客户组织编码，格式如 `CUS-202601-0001`）。**后续调用所有 V3 接口时，请求体都必须传入这个 `appId` 值**，且要与 token 所属的客户组织匹配，否则返回 `code: 61 "登录已过期"`。
⚠️ **不要把 `appKey`（API 账号标识）当成 `appId` 使用。** `appKey` 只用于获取 token。
:::
权限控制：调用接口需具备对应接口资源的访问权限，权限与 API 账号所属权限组关联。未配置资源时，按当前开放策略放行。
docs/openapi/v3/query.md
+783
View File
@@ -0,0 +1,783 @@
---
title: 查询类
description: iotLCM V3 查询类接口
outline: deep
---
# 查询类
## 单卡基本信息查询
```http
POST /openapi/v3/query/sim-info
```
请求头：
```http
X-Access-Token: {accessToken}
```
请求体：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| appId | string | 客户组织编码 |
| iccid | string | ICCID，`iccid`、`msisdn`、`imsi` 至少传一个 |
| msisdn | string | MSISDN |
| imsi | string | IMSI |
请求示例：
```json
{
"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` |
响应示例：
```json
{
"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
}
```
## 单卡状态信息查询
```http
POST /openapi/v3/query/sim-status
```
请求头：
```http
X-Access-Token: {accessToken}
```
请求体：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `appId` | string | token 返回的客户组织编码 |
| `iccid` | string | ICCID；与 `msisdn`、`imsi` 至少传一个 |
| `msisdn` | string | MSISDN |
| `imsi` | string | IMSI |
请求示例：
```json
{
"appId": "CUS-202601-0001",
"iccid": "898604F4152391115474"
}
```
响应结构：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | number | 业务状态码，成功为 `0` |
| `message` | string | 错误或提示信息 |
| `data.iccid` | string | ICCID，查询命中时返回 |
| `data.lifeCycle` | number | 卡生命周期状态编码 |
| `data.lifeCycleName` | string | 卡生命周期状态文字 |
| `error` | any | 错误信息字段 |
响应示例（查询命中）：
```json
{
"code": 0,
"message": "",
"data": {
"iccid": "898604F4152391115474",
"lifeCycle": 2,
"lifeCycleName": "已激活"
},
"error": null
}
```
响应示例（未命中）：
```json
{
"code": 50,
"message": "查询sim卡信息失败，请确认ICCID，MSISDN，IMSI是否正确",
"data": {},
"error": null
}
```
`lifeCycleName` 为状态文字；`lifeCycle` 是此接口的状态编码，不要与其他接口或字典中的状态编码混用。
## 单卡流量限额查询
```http
POST /openapi/v3/query/sim-limit
```
请求体：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `appId` | string | 客户组织编码 |
| `iccid` | string | ICCID |
| `msisdn` | string | MSISDN |
| `imsi` | string | IMSI |
请求示例：
```json
{
"appId": "CUS-202601-0001",
"iccid": "898604F4152391115474"
}
```
响应字段：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `data.trafficCutoffStatus` | integer | 达量断网状态：`0` 未配置、`1` 已开启、`2` 已关闭 |
| `data.trafficCutoffName` | string | 状态名称，返回 `未配置`、`已开启` 或 `已关闭` |
| `data.trafficCutoffThreshold` | number | 达量断网阈值，单位 MB |
响应示例：
```json
{
"code": 0,
"message": "",
"data": {
"trafficCutoffStatus": 1,
"trafficCutoffName": "已开启",
"trafficCutoffThreshold": 1024
},
"error": null
}
```
## 单卡实时终端 IMEI 查询
```http
POST /openapi/v3/query/sim-imei
```
请求体：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| appId | string | 客户组织编码 |
| iccid | string | ICCID |
| msisdn | string | MSISDN |
| imsi | string | IMSI |
请求示例：
```json
{
"appId": "CUS-202601-0001",
"iccid": "898604F4152391115474"
}
```
响应结构：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `data.imei` | string | IMEI |
响应示例：
```json
{
"code": 0,
"message": "",
"data": {
"imei": ""
},
"error": null
}
```
## 单卡本月流量使用量查询
```http
POST /openapi/v3/query/sim-usage
```
请求体：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| appId | string | 客户组织编码 |
| iccid | string | ICCID |
| msisdn | string | MSISDN |
| imsi | string | IMSI |
请求示例：
```json
{
"appId": "CUS-202601-0001",
"iccid": "898604F4152391115474"
}
```
响应结构：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `data.useUnit` | string | 流量单位，固定为 `MB` |
| `data.useAmount` | number | 当前周期已用流量 |
响应示例：
```json
{
"code": 0,
"message": "",
"data": {
"useUnit": "MB",
"useAmount": 0.875
},
"error": null
}
```
## 物联网卡批量状态信息查询
```http
POST /openapi/v3/query/sim-status-batch
```
单次最多查询 1000 张卡。每张卡至少提供 `iccid`、`msisdn`、`imsi` 中的一个；同一条记录提供多个标识时，必须对应同一张卡。
请求头：
```http
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 标识卡片 |
请求示例：
```json
{
"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 | 错误信息字段 |
响应示例：
```json
{
"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
}
```
## 物联网卡批量流量信息查询
```http
POST /openapi/v3/query/sim-usage-batch
```
单次最多查询 1000 张卡。请求体需传入 `appId` 和 `cards` 数组；数组中的每张卡至少提供 `iccid`、`msisdn`、`imsi` 中的一个。同一条记录提供多个标识时，必须对应同一张卡。
请求头：
```http
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 标识卡片 |
请求示例：
```json
{
"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 | 错误信息字段 |
响应示例：
```json
{
"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 查询
```http
POST /openapi/v3/query/sim-imei-batch
```
单次最多查询 1000 张卡。每张卡至少提供 `iccid`、`msisdn`、`imsi` 中的一个；同一条记录提供多个标识时，必须对应同一张卡。
请求头：
```http
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 标识卡片 |
请求示例：
```json
{
"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 | 错误信息字段 |
响应示例：
```json
{
"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
}
```
## 物联网卡批量限额信息查询
```http
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 | 是否返回套餐和流量使用信息 |
请求示例：
```json
{
"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 | 匹配失败时返回 |
响应示例：
以下状态、阈值和流量数值用于展示批量响应结构，实际结果以接口查询为准。
```json
{
"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
}
```
## 批次状态查询
```http
POST /openapi/v3/query/batch-status
```
根据指定批次号查询异步处理状态，支持续费、达量断网等异步批次。
请求参数：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `appId` | string | 客户组织编码 |
| `batchNo` | string | 异步 API 返回的批次号 |
请求示例：
```json
{
"appId": "CUS-202601-0001",
"batchNo": "REN20260910153546001000001"
}
```
响应结构：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `data.batchNo` | string | 请求中的批次号 |
| `data.batchAsyncStatus` | integer | 异步状态：`0` 已创建、`1` 待处理、`2` 处理中、`3` 成功、`4` 失败、`5` 部分成功 |
响应示例：
```json
{
"code": 0,
"message": "",
"data": {
"batchNo": "REN20260910153546001000001",
"batchAsyncStatus": 3
},
"error": null
}
```
docs/openapi/v3/token.md
+57
View File
@@ -0,0 +1,57 @@
---
title: 获取调用凭证
description: 使用 appKey、appSecret 换取 V3 接口调用凭证
outline: deep
---
# 获取调用凭证
```http
POST /openapi/v3/query/token
```
说明：使用 `appKey`、`appSecret` 换取接口调用凭证。
请求体：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| appKey | string | API 账号标识，在管理后台申请获取 |
| appSecret | string | API 密钥，在管理后台申请获取 |
| refresh | string | 是否刷新 token：`1` 强制生成新 token，`0` 或留空时尽量复用已有 token |
请求示例：
```json
{
"appKey": "YOUR_APP_ID",
"appSecret": "YOUR_APP_SECRETebdebae9763127943f097758e029a0fdbc"
}
```
响应结构：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| data.appId | string | 客户组织编码，**后续所有接口请求体中都要传入此值** |
| data.accessToken | string | 接口调用凭证，后续放入 `X-Access-Token` |
::: info 注意：appId ≠ appKey
- **`appKey`**（如 `SDYZ`）只用于获取 token，调用 `/openapi/v3/query/token` 后就不再需要
- **`appId`**（如 `CUS-202601-0001`）由 token 接口返回，后续调用 sim-info 等接口时，请求体中的 `appId` 字段必须填这个值
- 如果传错会导致 `code: 61 "登录已过期"` 错误
:::
响应示例：
```json
{
"code": 0,
"message": "",
"data": {
"appId": "CUS-202601-0001",
"accessToken": "eyJhbGciOiJIUzI1NiJ9.eyJ1IjoiZWE3ZjJiZGY5MjQyNDFkZjg3NGIwZDMzNmZkN2UzMzEiLCJleHAiOjE3ODQ3MDAyODB9.JiYK-CXdXQKKU0UNhNOqKX5Hzyk4lVMtIpunQJDxlBI"
},
"error": null
}
```