---
title: 业务类
description: iotLCM V3 业务类接口
outline: deep
---

# 业务类

## 服务地址

```text
https://apiv3.5iot.cn
```

HTTP（`http://apiv3.5iot.cn`）仅为存量兼容保留，不做自动跳转，新接入请使用 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
}
```