iotlcm-public/iotlcm
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b4944d7c2173a9aa393743ef30d25c2b27bcc413
iotlcm/docs/openapi/v3/common.md
T
MiFaZhan 3ab3682d14 sync: 同步文档 v1.0.4 并脱敏
2026-10-29 15:45:46 +08:00

9.0 KiB
Raw Blame History

title, description, outline
title description outline
业务类 iotLCM V3 业务类接口 deep

业务类

服务地址

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 仅查询配置。

统一返回结构

{
    "code": 0,
    "message": "",
    "data": {},
    "error": null
}
字段 类型 说明
code number 业务状态码，成功为 0
message string 错误或提示信息
data object 业务数据
error any 错误详情

单卡套餐续费

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 至少传一个。

请求示例：

{
    "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 失败时返回的错误说明

响应示例：

{
    "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 说明失败原因。

{
    "code": 0,
    "message": "",
    "data": {
        "orderId": "0",
        "orderSn": "",
        "iccid": "89860400000000005152",
        "planName": "",
        "effectiveType": "",
        "effectiveDate": "",
        "expireDate": "",
        "amount": 0,
        "status": "failed",
        "errorCode": "RENEW_FAILED",
        "errorMessage": "卡片不存在或无权限"
    },
    "error": null
}

单卡限额变更

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 表示取消达量断网配置。

请求示例：

{
    "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 失败时的错误编码

响应示例：

{
    "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 为失败原因。

{
    "code": 0,
    "message": "",
    "data": {
        "success": false,
        "iccid": "89860400000000005152",
        "trafficCutoffStatus": 1,
        "trafficCutoffThreshold": 1024,
        "trafficCutoffThresholdUnit": "MB",
        "message": "卡片不存在或无权限",
        "errorCode": "TRAFFIC_CUTOFF_FAILED"
    },
    "error": null
}

物联网卡批量套餐续费

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 三码至少传一个。

请求示例：

{
    "appId": "CUS-202608-0001",
    "cards": [
        {
            "iccid": "89860400000000005152"
        }
    ],
    "packageId": "001",
    "validity": 1,
    "remark": "客户批量续费"
}

响应字段：

字段 类型 说明
batchNo string 系统生成的续费批次号
batchType integer 批次类型，续费为 101
total integer 提交的卡数量

响应示例：

{
    "code": 0,
    "message": "",
    "data": {
        "batchNo": "REN20260910153546001000002",
        "batchType": 101,
        "total": 1
    },
    "error": null
}

物联网卡批量限额变更

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时表示取消达量断网配置。

请求示例：

{
    "appId": "CUS-202608-0001",
    "cards": [
        {
            "iccid": "89860400000000005152"
        }
    ],
    "trafficCutoffStatus": 1,
    "trafficCutoffThreshold": 1024,
    "remark": "客户批量开启达量断网"
}

响应字段：

字段 类型 说明
batchNo string 系统生成的达量断网配置批次号
batchType integer 批次类型，达量断网配置为 41

响应示例：

{
    "code": 0,
    "message": "",
    "data": {
        "batchNo": "TCC20260910153546001000001",
        "batchType": 41
    },
    "error": null
}
Reference in New Issue View Git Blame Copy Permalink