MiFaZhan
353 lines
9.0 KiB
Markdown
353 lines
9.0 KiB
Markdown
---
|
||
title: 业务类
|
||
description: iotLCM V3 业务类接口
|
||
outline: deep
|
||
---
|
||
|
||
# 业务类
|
||
|
||
## 服务地址
|
||
|
||
```text
|
||
https://api.example.com
|
||
```
|
||
|
||
HTTP（`http://api.example.com`）仅为存量兼容保留，不做自动跳转，新接入请使用 HTTPS。
|
||
|
||
## 鉴权
|
||
|
||
先调用 `/openapi/v3/query/token` 获取访问令牌，再在请求头中传入 `X-Access-Token`。请求体中的 `appId` 必须与凭证所属客户一致。
|
||
|
||
## 标准入口与兼容入口
|
||
|
||
新接入统一使用本文的 `/openapi/v3/change/*` 路径。原 `/openapi/v3/common/*` 前缀已停止提供，调用返回 `404`，请改用 `/change` 下的对应接口。
|
||
|
||
批量续费使用 `/change/batch-sim-subscribe`；历史 `/change/renew` 接收 `cards[]`，允许每张卡携带套餐信息，作为兼容入口保留。两者共用续费实现。
|
||
|
||
批量变更达量断网使用 `/change/batch-sim-traffic-cutoff`。原 `/change/traffic-cutoff-config` 不再对外提供，请改用标准入口——两者请求参数完全一致，迁移无需改动报文体。`/query/traffic-cutoff-config` 仅查询配置。
|
||
|
||
## 统一返回结构
|
||
|
||
```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": "89860400000000005152",
|
||
"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": "89860400000000005152",
|
||
"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": "89860400000000005152",
|
||
"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": "89860400000000005152",
|
||
"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": "89860400000000005152",
|
||
"msisdn": "14100005152",
|
||
"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": "89860400000000005152",
|
||
"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": "89860400000000005152"
|
||
}
|
||
],
|
||
"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": "89860400000000005152"
|
||
}
|
||
],
|
||
"trafficCutoffStatus": 1,
|
||
"trafficCutoffThreshold": 1024,
|
||
"remark": "客户批量开启达量断网"
|
||
}
|
||
```
|
||
|
||
响应字段：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `batchNo` | string | 系统生成的达量断网配置批次号 |
|
||
| `batchType` | integer | 批次类型，达量断网配置为 `41` |
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "",
|
||
"data": {
|
||
"batchNo": "TCC20260910153546001000001",
|
||
"batchType": 41
|
||
},
|
||
"error": null
|
||
}
|
||
```
|