Files

T

Dai0814 846bac3d6c docs: publish API examples from open-source

2026-10-26 16:19:42 +08:00

4.6 KiB

Raw Blame History

title, description, outline

title	description	outline
白名单转发	通过 apiv3.5iot.cn 访问中国移动物联网能力开放平台 V5 接口	deep

白名单转发

本目录说明如何通过 apiv3.5iot.cn 访问中国移动物联网能力开放平台 V5 接口。平台仅提供安全代理转发，不改变中国移动 V5 接口的请求方法、请求参数、响应结构和业务语义。

服务地址

客户侧统一使用：

https://apiv3.5iot.cn

V5 接口的请求路径保持与中国移动官方接口一致，将官方域名替换为平台域名即可：

https://apiv3.5iot.cn/v5/{官方接口路径}

例如，官方接口路径为 /v5/ec/query/sim-basic-info 时，客户侧请求路径为：

POST https://apiv3.5iot.cn/v5/ec/query/sim-basic-info

平台会将该请求转发至：

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 接口清单，用于说明代理路径的写法。完整接口、字段、错误码和版本变更请以官方文档为准。

单卡基本信息查询

POST https://apiv3.5iot.cn/v5/ec/query/sim-basic-info

请求参数：

参数	类型	说明
`transid`	string	事务编码
`token`	string	V5 Token
`msisdn`	string	物联卡号码
`iccid`	string	ICCID；与 `msisdn`、`imsi` 按官方规则选择
`imsi`	string	IMSI

请求示例：

{
    "transid": "113712264334542026051515200001000",
    "token": "c5e1cad63e654237052be9908f989bf3515b3bdaeca904dd2e904061b65e8153",
    "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	开卡时间

响应示例：

{
    "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 接口文档下载页面

平台代理入口仅替换访问域名，不替代中国移动官方接口规范。

4.6 KiB Raw Blame History