chore: 初始开源发布

2026-10-22 15:16:43 +08:00
commit 92f239fcc4
114 changed files with 8018 additions and 0 deletions
@@ -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)
+
+平台代理入口仅替换访问域名，不替代中国移动官方接口规范。