---
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)

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