chore: 初始开源发布
This commit is contained in:
MiFaZhan
@@ -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
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user