1370 lines
30 KiB
Markdown
1370 lines
30 KiB
Markdown
# BaseUrl: https://cmp-api.xm-iot.cn
|
||
|
||
错误响应示例：
|
||
{
|
||
"code": 1001,
|
||
"msg": "参数验证失败",
|
||
"data": {},
|
||
"timestamp": "2026-03-20T10:00:00Z"
|
||
}
|
||
|
||
# 2. 认证
|
||
|
||
## 2.1 资产验证
|
||
|
||
URL：
|
||
POST /api/c/v1/auth/verify-asset
|
||
|
||
请求说明：
|
||
- 请求方式：POST
|
||
- 认证方式：无需认证
|
||
- Content-Type：application/json
|
||
|
||
请求体参数：
|
||
- identifier（string，必填）- 资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）
|
||
|
||
请求示例：
|
||
{
|
||
"identifier": "1234567890"
|
||
}
|
||
|
||
成功响应示例：
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"timestamp": "2026-03-20T10:00:00Z",
|
||
"data": {
|
||
"asset_token": "asset_token_example",
|
||
"expires_in": 300
|
||
}
|
||
}
|
||
|
||
字段说明：
|
||
data：
|
||
- asset_token：资产令牌（5分钟有效）
|
||
- expires_in：过期时间（秒）
|
||
|
||
|
||
|
||
## 2.2 公众号登录接口
|
||
|
||
## 接口信息
|
||
- **路径**：`POST /api/c/v1/auth/wechat-login`
|
||
- **说明**：公众号登录（通过微信 OAuth code 登录）
|
||
- **认证**：无需登录
|
||
|
||
---
|
||
|
||
## 请求参数
|
||
|
||
### Body（application/json）
|
||
|
||
```json
|
||
{
|
||
"asset_token": "string",
|
||
"code": "string"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 参数说明
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| asset_token | 是 | A1 返回的资产令牌 |
|
||
| code | 是 | 微信 OAuth 授权码 | wxea8c599fe100ce8a 先临时用这个
|
||
|
||
---
|
||
|
||
## 返回结构
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"timestamp": "2026-04-01T10:00:00Z",
|
||
"data": {
|
||
"is_new_user": false,
|
||
"need_bind_phone": false,
|
||
"token": "jwt_token"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## data 字段说明
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| is_new_user | 是否新用户 |
|
||
| need_bind_phone | 是否需要绑定手机号 |
|
||
| token | 登录后的 JWT Token |
|
||
|
||
## 2.3 发送验证码
|
||
|
||
URL：
|
||
POST /api/c/v1/auth/send-code
|
||
|
||
请求说明：
|
||
- 请求方式：POST
|
||
- 认证方式：无需认证
|
||
- Content-Type：application/json
|
||
|
||
请求体参数：
|
||
- phone（string，必填）- 手机号（11位）
|
||
- scene（string，必填）- 业务场景（bind_phone:绑定手机号, change_phone_old:换绑旧手机, change_phone_new:换绑新手机）
|
||
|
||
请求示例：
|
||
{
|
||
"phone": "13800138000",
|
||
"scene": "bind_phone"
|
||
}
|
||
|
||
成功响应示例：
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"timestamp": "2026-03-20T10:00:00Z",
|
||
"data": {
|
||
"cooldown_seconds": 60
|
||
}
|
||
}
|
||
|
||
字段说明：
|
||
data：
|
||
- cooldown_seconds：冷却秒数
|
||
|
||
|
||
|
||
## 2.4 绑定手机号
|
||
|
||
URL：
|
||
POST /api/c/v1/auth/bind-phone
|
||
|
||
请求说明：
|
||
- 请求方式：POST
|
||
- 认证方式：Bearer Token（JWT）
|
||
- Content-Type：application/json
|
||
|
||
请求体参数：
|
||
- phone（string，必填）- 手机号（11位）
|
||
- code（string，必填）- 验证码（6位）
|
||
|
||
请求示例：
|
||
{
|
||
"phone": "13800138000",
|
||
"code": "123456"
|
||
}
|
||
|
||
成功响应示例：
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"timestamp": "2026-03-20T10:00:00Z",
|
||
"data": {
|
||
"phone": "13800138000",
|
||
"bound_at": "2026-03-20T10:00:00Z"
|
||
}
|
||
}
|
||
|
||
字段说明：
|
||
data：
|
||
- phone：已绑定手机号
|
||
- bound_at：绑定时间
|
||
|
||
|
||
|
||
|
||
## 2.5 更换手机号
|
||
|
||
URL：
|
||
POST /api/c/v1/auth/change-phone
|
||
|
||
请求说明：
|
||
- 请求方式：POST
|
||
- 认证方式：Bearer Token（JWT）
|
||
- Content-Type：application/json
|
||
|
||
请求体参数：
|
||
- old_phone（string，必填）- 旧手机号（11位）
|
||
- old_code（string，必填）- 旧手机号验证码（6位）
|
||
- new_phone（string，必填）- 新手机号（11位）
|
||
- new_code（string，必填）- 新手机号验证码（6位）
|
||
|
||
请求示例：
|
||
{
|
||
"old_phone": "13800138000",
|
||
"old_code": "123456",
|
||
"new_phone": "13900139000",
|
||
"new_code": "654321"
|
||
}
|
||
|
||
成功响应示例：
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"timestamp": "2026-03-20T10:00:00Z",
|
||
"data": {
|
||
"phone": "13900139000",
|
||
"changed_at": "2026-03-20T10:00:00Z"
|
||
}
|
||
}
|
||
|
||
字段说明：
|
||
data：
|
||
- phone：换绑后手机号
|
||
- changed_at：换绑时间
|
||
|
||
|
||
|
||
## 2.6 退出登录
|
||
|
||
URL：
|
||
POST /api/c/v1/auth/logout
|
||
|
||
请求说明：
|
||
- 请求方式：POST
|
||
- 认证方式：Bearer Token（JWT）
|
||
|
||
请求示例：
|
||
（无请求体）
|
||
|
||
成功响应示例：
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"timestamp": "2026-03-20T10:00:00Z",
|
||
"data": {
|
||
"success": true
|
||
}
|
||
}
|
||
|
||
字段说明：
|
||
data：
|
||
- success：是否成功
|
||
|
||
|
||
url: /api/c/v1/asset/info
|
||
请求地址的响应发生变化, 请根据变化来调整首页里面的数据 我有在响应后面加了注释
|
||
然后到期时间: 拿的是 资产套餐历史 列表里面的 "status_name": "生效中",expires_at
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"asset_type": "device", // isDevice: true, 如果是device就是true
|
||
"asset_id": 1,
|
||
"identifier": "862639070804960", // 当前卡
|
||
"virtual_no": "862639070804960",
|
||
"status": 1, // 状态 到期时间右边那个
|
||
"real_name_status": 0, // 实名状态
|
||
"carrier_name": "", // 运营商
|
||
"generation": "1",
|
||
"wallet_balance": 0,
|
||
"current_package": "",
|
||
"package_total_mb": 0,
|
||
"package_used_mb": 0,
|
||
"package_remain_mb": 0,
|
||
"device_name": "WiFi1",
|
||
"imei": "862639070804960",
|
||
"device_model": "WM-2000",
|
||
"device_type": "WiFi",
|
||
"manufacturer": "华为",
|
||
"max_sim_slots": 4,
|
||
"bound_card_count": 1,
|
||
"cards": [
|
||
{
|
||
"card_id": 5,
|
||
"iccid": "89860441192590297661",
|
||
"msisdn": "13800138000",
|
||
"network_status": 0,
|
||
"real_name_status": 0,
|
||
"slot_position": 1,
|
||
"is_current": false
|
||
}
|
||
],
|
||
"device_protect_status": "none",
|
||
"device_realtime": {
|
||
"gateway_msg": null,
|
||
"online_status": 1, // 在线状态（1:在线, 2:离线）
|
||
"battery_level": 100, // 设备电量
|
||
"status": 0,
|
||
"run_time": "527020",
|
||
"connect_time": "239077",
|
||
"rsrp": -78, // 根据这三个计算出网络信号
|
||
"rsrq": -9, // 根据这三个计算出网络信号
|
||
"rssi": "-47", // 根据这三个计算出网络信号
|
||
"sinr": 12,
|
||
"ssid": "MiFi-DA78", // WiFi名称
|
||
"wifi_enabled": true,
|
||
"wifi_password": "1234567890", // WiFi密码
|
||
"wan_ip": "10.99.164.211",
|
||
"lan_ip": "192.168.1.1", // 点击后台管理
|
||
"mac_address": "60:83:e2:01:da:78",
|
||
"daily_usage": "3321987788",
|
||
"dl_stats": "0",
|
||
"ul_stats": "0",
|
||
"limit_speed": 0,
|
||
"max_clients": 1, // 放到连接数里面 现在换成 client_number/max_clients
|
||
"client_number": 1, // 已连接数 现在换成 client_number/max_clients
|
||
"software_version": "LBF2AKAS01070_N20_8_ESIM_V001",
|
||
"sync_interval": 120,
|
||
"device_id": "862639070804960",
|
||
"imei": "862639070804960",
|
||
"imsi": "460068049567506"
|
||
}
|
||
},
|
||
"msg": "success",
|
||
"timestamp": "2026-03-30T09:21:25+08:00"
|
||
}
|
||
```
|
||
|
||
|
||
# 3. 资产
|
||
|
||
## 3.1 资产信息
|
||
|
||
URL：
|
||
GET /api/c/v1/asset/info
|
||
|
||
更新说明（2026-05-08）：
|
||
* 本月流量展示以该接口返回字段为准
|
||
* 总流量：`real_total_mb`
|
||
* 已使用：`enable_virtual_data=true` 时取 `virtual_used_mb`，否则取 `real_used_mb`
|
||
* 剩余：`real_total_mb - 已使用`
|
||
* 进度条：`已使用 / real_total_mb`
|
||
|
||
Query 参数：
|
||
identifier（string，必填）- 资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）
|
||
|
||
请求说明：
|
||
- 请求方式：GET
|
||
- 认证方式：Bearer Token（JWT）
|
||
|
||
请求示例：
|
||
/api/c/v1/asset/info?identifier=1234567890
|
||
|
||
成功响应示例：
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"timestamp": "2026-03-20T10:00:00Z",
|
||
"data": {
|
||
"asset_id": 1,
|
||
"asset_type": "device",
|
||
"carrier_name": "中国移动",
|
||
"generation": "4G",
|
||
"identifier": "1234567890",
|
||
"real_name_status": 1,
|
||
"status": 1,
|
||
"virtual_no": "17000000000",
|
||
"wallet_balance": 1000
|
||
}
|
||
}
|
||
|
||
字段说明：
|
||
data：
|
||
- asset_id：资产ID
|
||
- asset_type：资产类型（card:卡, device:设备）
|
||
- carrier_name：运营商名称
|
||
- generation：制式
|
||
- identifier：资产标识符
|
||
- real_name_status：实名状态（0:未实名, 1:已实名）
|
||
- status：状态（0:禁用, 1:启用）
|
||
- virtual_no：虚拟号
|
||
- wallet_balance：钱包余额（分）
|
||
|
||
|
||
## 3.2 资产套餐历史
|
||
|
||
URL：
|
||
GET /api/c/v1/asset/package-history
|
||
|
||
更新说明（2026-05-08）：
|
||
* 涉及“本月流量”展示时，以 `/api/c/v1/asset/info` 的规则为准
|
||
* 旧说明中“启用虚流量时总流量/剩余切换为虚流量”的规则已废弃
|
||
* 当前规则：总流量固定取 `real_total_mb`，已使用按 `enable_virtual_data` 在 `virtual_used_mb` / `real_used_mb` 间切换，剩余和进度条按该结果计算
|
||
|
||
Query 参数：
|
||
- identifier（string，必填）- 资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）
|
||
- page（integer，必填）- 页码
|
||
- page_size（integer，必填）- 每页数量
|
||
- package_type（string，可选）- 套餐类型 (formal:正式套餐, addon:加油包)
|
||
- status（integer，必填）- 套餐状态 (0:待生效, 1:生效中, 2:已用完, 3:已过期, 4:已失效)
|
||
|
||
请求说明：
|
||
- 请求方式：GET
|
||
- 认证方式：Bearer Token（JWT）
|
||
|
||
请求示例：
|
||
GET /api/c/v1/asset/package-history?identifier=1234567890&page=1&page_size=10
|
||
|
||
成功响应示例：
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"timestamp": "2026-03-20T10:00:00Z",
|
||
"data": {
|
||
"items": [
|
||
{
|
||
"activated_at": "2026-03-01T00:00:00Z",
|
||
"created_at": "2026-03-01T00:00:00Z",
|
||
"data_limit_mb": 10240,
|
||
"data_usage_mb": 2048,
|
||
"expires_at": "2026-03-31T23:59:59Z",
|
||
"master_usage_id": null,
|
||
"package_id": 1001,
|
||
"package_name": "10GB月套餐",
|
||
"package_type": "formal",
|
||
"package_usage_id": 5001,
|
||
"priority": 1,
|
||
"status": 1,
|
||
"enable_virtual_data": true,
|
||
"status_name": "生效中",
|
||
"usage_type": "single_card",
|
||
"virtual_limit_mb": 20480,
|
||
"virtual_ratio": 0.5,
|
||
"virtual_remain_mb": 16384,
|
||
"virtual_used_mb": 4096
|
||
}
|
||
],
|
||
"page": 1,
|
||
"page_size": 10,
|
||
"total": 1
|
||
}
|
||
}
|
||
|
||
字段说明：
|
||
data：
|
||
- items：套餐历史列表
|
||
- page：页码
|
||
- page_size：每页数量
|
||
- total：总数
|
||
|
||
data.items[]：
|
||
- activated_at：激活时间（待生效套餐为空）
|
||
- created_at：创建时间
|
||
- data_limit_mb：套餐真流量总量(MB)
|
||
- data_usage_mb：已用真流量(MB)
|
||
- expires_at：到期时间（待生效套餐为空）
|
||
- master_usage_id：主套餐ID（加油包时有值）
|
||
- package_id：套餐ID
|
||
- package_name：套餐名称
|
||
- package_type：套餐类型（formal 普通类型 / addon 加油包）
|
||
- package_usage_id：套餐使用记录ID
|
||
- priority：优先级
|
||
- status：状态（0待生效 1生效中 2已用完 3已过期 4已失效）
|
||
- status_name：状态名称
|
||
- usage_type：使用类型（single_card/device）
|
||
- virtual_limit_mb：套餐虚流量总量(MB)，按virtual_ratio换算
|
||
- virtual_ratio：虚流量比例(real/virtual)
|
||
- virtual_remain_mb：剩余虚流量(MB)，按virtual_ratio换算
|
||
- virtual_used_mb：已用虚流量(MB)，按virtual_ratio换算
|
||
- enable_virtual_data：是否启用虚流量
|
||
* 如果启用了虚流量那么 本月流量展示的就是 套餐虚流量总量 剩余虚流量 已用虚流量 只是值用这些,已使用,总流量,剩余不要改
|
||
* 如果没有启用那就是 套餐真流量总量 已用真流量 剩余真流量(自己计算) 然后如果大于或者等于1024MB 转换成 GB
|
||
* 本月流量哪里需要调用这个接口,带上参数status: 1:生效中 只会有一个生效的
|
||
*
|
||
## 3.3 资产可购套餐列表
|
||
|
||
URL：
|
||
GET /api/c/v1/asset/packages
|
||
|
||
Query 参数：
|
||
- identifier（string，必填）- 资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）
|
||
|
||
请求说明：
|
||
- 请求方式：GET
|
||
- 认证方式：Bearer Token（JWT）
|
||
|
||
请求示例：
|
||
GET /api/c/v1/asset/packages?identifier=1234567890
|
||
|
||
成功响应示例：
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"timestamp": "2026-03-20T10:00:00Z",
|
||
"data": {
|
||
"packages": [
|
||
{
|
||
"cost_price": 1000,
|
||
"data_allowance": 10240,
|
||
"data_unit": "MB",
|
||
"description": "适用于日常上网使用",
|
||
"is_addon": false,
|
||
"package_id": 1001,
|
||
"package_name": "10GB月套餐",
|
||
"package_type": "formal",
|
||
"retail_price": 1500,
|
||
"validity_days": 30
|
||
}
|
||
]
|
||
}
|
||
}
|
||
|
||
字段说明：
|
||
data：
|
||
- packages：套餐列表
|
||
|
||
data.packages[]：
|
||
- cost_price：成本价（分）
|
||
- data_allowance：流量额度
|
||
- data_unit：流量单位
|
||
- description：套餐说明
|
||
- is_addon：是否加油包
|
||
- package_id：套餐ID
|
||
- package_name：套餐名称
|
||
- package_type：套餐类型（formal:正式套餐, addon:加油包）
|
||
- retail_price：零售价（分）
|
||
- validity_days：有效天数
|
||
|
||
|
||
## 3.4 资产刷新
|
||
|
||
URL：
|
||
POST /api/c/v1/asset/refresh
|
||
|
||
请求说明：
|
||
- 请求方式：POST
|
||
- 认证方式：Bearer Token（JWT）
|
||
- Content-Type：application/json
|
||
|
||
请求体参数：
|
||
- identifier（string，必填）- 资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）
|
||
|
||
请求示例：
|
||
{
|
||
"identifier": "1234567890"
|
||
}
|
||
|
||
成功响应示例：
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"timestamp": "2026-03-20T10:00:00Z",
|
||
"data": {
|
||
"accepted": true,
|
||
"cooldown_seconds": 60,
|
||
"refresh_type": "device"
|
||
}
|
||
}
|
||
|
||
字段说明：
|
||
data：
|
||
- accepted：是否已受理
|
||
- cooldown_seconds：冷却秒数
|
||
- refresh_type：刷新类型（card:卡, device:设备）
|
||
|
||
|
||
# 4. 设备
|
||
|
||
## 4.1 获取设备卡列表
|
||
|
||
URL：
|
||
GET /api/c/v1/device/cards
|
||
|
||
Query 参数：
|
||
- identifier（string，必填）- 资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）
|
||
|
||
请求说明：
|
||
- 请求方式：GET
|
||
- 认证方式：Bearer Token（JWT）
|
||
|
||
请求示例：
|
||
GET /api/c/v1/device/cards?identifier=1234567890
|
||
|
||
成功响应示例：
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"timestamp": "2026-03-20T10:00:00Z",
|
||
"data": {
|
||
"cards": [
|
||
{
|
||
"card_id": 1,
|
||
"carrier_name": "中国移动",
|
||
"iccid": "89860012345678901234",
|
||
"is_active": true,
|
||
"msisdn": "17000000000",
|
||
"network_status": "online",
|
||
"real_name_status": 1,
|
||
"slot_position": 1
|
||
}
|
||
]
|
||
}
|
||
}
|
||
|
||
字段说明：
|
||
data：
|
||
- cards：设备卡列表
|
||
|
||
data.cards[]：
|
||
- card_id：卡ID
|
||
- carrier_name：运营商名称
|
||
- iccid：物联网卡ICCID
|
||
- is_active：是否当前激活卡
|
||
- msisdn：手机号
|
||
- network_status：网络状态
|
||
- real_name_status：实名状态（0:未实名, 1:已实名）
|
||
- slot_position：插槽位置
|
||
|
||
## 4.2 恢复出厂设置
|
||
URL：
|
||
POST /api/c/v1/device/factory-reset
|
||
|
||
请求说明：
|
||
- 请求方式：POST
|
||
- 认证方式：Bearer Token（JWT）
|
||
- Content-Type：application/json
|
||
|
||
请求体参数：
|
||
- identifier（string，必填）- 资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）
|
||
|
||
请求示例：
|
||
{
|
||
"identifier": "1234567890"
|
||
}
|
||
|
||
成功响应示例：
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"timestamp": "2026-03-20T10:00:00Z",
|
||
"data": {
|
||
"accepted": true,
|
||
"request_id": "req_123456789"
|
||
}
|
||
}
|
||
|
||
字段说明：
|
||
data：
|
||
- accepted：是否已受理
|
||
- request_id：请求ID
|
||
|
||
## 4.3 设备重启
|
||
|
||
URL：
|
||
POST /api/c/v1/device/reboot
|
||
|
||
请求说明：
|
||
- 请求方式：POST
|
||
- 认证方式：Bearer Token（JWT）
|
||
- Content-Type：application/json
|
||
|
||
请求体参数：
|
||
- identifier（string，必填）- 资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）
|
||
|
||
请求示例：
|
||
{
|
||
"identifier": "1234567890"
|
||
}
|
||
|
||
成功响应示例：
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"timestamp": "2026-03-20T10:00:00Z",
|
||
"data": {
|
||
"accepted": true,
|
||
"request_id": "req_123456789"
|
||
}
|
||
}
|
||
|
||
字段说明：
|
||
data：
|
||
- accepted：是否已受理
|
||
- request_id：请求ID
|
||
|
||
## 4.4 设备切卡
|
||
|
||
URL：
|
||
POST /api/c/v1/device/switch-card
|
||
|
||
请求说明：
|
||
- 请求方式：POST
|
||
- 认证方式：Bearer Token（JWT）
|
||
- Content-Type：application/json
|
||
|
||
请求体参数：
|
||
- identifier（string，必填）- 资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）
|
||
- target_iccid（string，必填）- 目标ICCID
|
||
|
||
请求示例：
|
||
{
|
||
"identifier": "1234567890",
|
||
"target_iccid": "89860012345678901234"
|
||
}
|
||
|
||
成功响应示例：
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"timestamp": "2026-03-20T10:00:00Z",
|
||
"data": {
|
||
"accepted": true,
|
||
"target_iccid": "89860012345678901234"
|
||
}
|
||
}
|
||
|
||
字段说明：
|
||
data：
|
||
- accepted：是否已受理
|
||
- target_iccid：目标ICCID
|
||
|
||
|
||
## 4.5 设备WiFi配置
|
||
|
||
URL：
|
||
POST /api/c/v1/device/wifi
|
||
|
||
请求说明：
|
||
- 请求方式：POST
|
||
- 认证方式：Bearer Token（JWT）
|
||
- Content-Type：application/json
|
||
|
||
请求体参数：
|
||
- enabled（boolean，必填）- 是否启用WiFi
|
||
- identifier（string，必填）- 资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）
|
||
- password（string，必填）- WiFi密码
|
||
- ssid（string，必填）- WiFi名称
|
||
|
||
请求示例：
|
||
{
|
||
"enabled": true,
|
||
"identifier": "1234567890",
|
||
"password": "12345678",
|
||
"ssid": "MyWiFi"
|
||
}
|
||
|
||
成功响应示例：
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"timestamp": "2026-03-20T10:00:00Z",
|
||
"data": {
|
||
"accepted": true,
|
||
"request_id": "req_123456789"
|
||
}
|
||
}
|
||
|
||
字段说明：
|
||
data：
|
||
- accepted：是否已受理
|
||
- request_id：请求ID
|
||
|
||
|
||
# 5. 换货
|
||
|
||
## 5.1 提交收货信息
|
||
|
||
URL：
|
||
POST /api/c/v1/exchange/{id}/shipping-info
|
||
|
||
Path 参数：
|
||
- id（integer，必填）- 换货单ID
|
||
|
||
请求说明：
|
||
- 请求方式：POST
|
||
- 认证方式：Bearer Token（JWT）
|
||
- Content-Type：application/json
|
||
|
||
请求体参数：
|
||
- recipient_address（string，必填）- 收货地址
|
||
- recipient_name（string，必填）- 收件人姓名
|
||
- recipient_phone（string，必填）- 收件人电话
|
||
|
||
请求示例：
|
||
{
|
||
"recipient_address": "广东省深圳市南山区科技园1号",
|
||
"recipient_name": "张三",
|
||
"recipient_phone": "13800138000"
|
||
}
|
||
|
||
成功响应示例：
|
||
（接口文档未定义成功响应示例，通常为 200/204，可根据后端实际返回补充）
|
||
|
||
字段说明：
|
||
请求体：
|
||
- recipient_address：收货地址
|
||
- recipient_name：收件人姓名
|
||
- recipient_phone：收件人电话
|
||
|
||
## 5.2 查询待处理换货单
|
||
|
||
URL：
|
||
GET /api/c/v1/exchange/pending
|
||
|
||
Query 参数：
|
||
- identifier（string，必填）- 资产标识符（ICCID/虚拟号/IMEI/SN）
|
||
|
||
请求说明：
|
||
- 请求方式：GET
|
||
- 认证方式：Bearer Token（JWT）
|
||
|
||
请求示例：
|
||
GET /api/c/v1/exchange/pending?identifier=1234567890
|
||
|
||
成功响应示例：
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"timestamp": "2026-03-20T10:00:00Z",
|
||
"data": {
|
||
"id": 1,
|
||
"exchange_no": "EX202603200001",
|
||
"exchange_reason": "设备故障",
|
||
"status": 1,
|
||
"status_text": "待填写信息",
|
||
"created_at": "2026-03-20T10:00:00Z"
|
||
}
|
||
}
|
||
|
||
字段说明：
|
||
data：
|
||
- id：换货单ID
|
||
- exchange_no：换货单号
|
||
- exchange_reason：换货原因
|
||
- status：换货状态（1:待填写信息, 2:待发货, 3:已发货待确认, 4:已完成, 5:已取消）
|
||
- status_text：换货状态文本
|
||
- created_at：创建时间
|
||
|
||
|
||
# 6. 订单
|
||
|
||
## 6.1 订单列表
|
||
|
||
URL：
|
||
GET /api/c/v1/orders
|
||
|
||
Query 参数：
|
||
- identifier（string，必填）- 资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）
|
||
- payment_status（integer，选填）- 支付状态（0:待支付, 1:已支付, 2:已取消）
|
||
- page（integer，必填）- 页码
|
||
- page_size（integer，必填）- 每页数量
|
||
|
||
请求说明：
|
||
- 请求方式：GET
|
||
- 认证方式：Bearer Token（JWT）
|
||
|
||
请求示例：
|
||
GET /api/c/v1/orders?identifier=1234567890&payment_status=1&page=1&page_size=10
|
||
|
||
成功响应示例：
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"timestamp": "2026-03-20T10:00:00Z",
|
||
"data": {
|
||
"items": [
|
||
{
|
||
"created_at": "2026-03-20T10:00:00Z",
|
||
"order_id": 1,
|
||
"order_no": "ORD202603200001",
|
||
"package_names": [
|
||
"10GB月套餐",
|
||
"5GB加油包"
|
||
],
|
||
"payment_status": 1,
|
||
"total_amount": 2500
|
||
}
|
||
],
|
||
"page": 1,
|
||
"page_size": 10,
|
||
"total": 1
|
||
}
|
||
}
|
||
|
||
字段说明：
|
||
data：
|
||
- items：订单列表
|
||
- page：页码
|
||
- page_size：每页数量
|
||
- total：总数
|
||
|
||
data.items[]：
|
||
- created_at：创建时间
|
||
- order_id：订单ID
|
||
- order_no：订单号
|
||
- package_names：套餐名称列表
|
||
- payment_status：支付状态（0:待支付, 1:已支付, 2:已取消）
|
||
- total_amount：订单总金额（分）
|
||
|
||
## 6.2 订单详情
|
||
|
||
URL：
|
||
GET /api/c/v1/orders/{id}
|
||
|
||
Path 参数：
|
||
- id（integer，必填）- 订单ID
|
||
|
||
请求说明：
|
||
- 请求方式：GET
|
||
- 认证方式：Bearer Token（JWT）
|
||
|
||
请求示例：
|
||
GET /api/c/v1/orders/1
|
||
|
||
成功响应示例：
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"timestamp": "2026-03-20T10:00:00Z",
|
||
"data": {
|
||
"completed_at": "2026-03-20T10:30:00Z",
|
||
"created_at": "2026-03-20T10:00:00Z",
|
||
"order_id": 1,
|
||
"order_no": "ORD202603200001",
|
||
"packages": [
|
||
{
|
||
"package_id": 1001,
|
||
"package_name": "10GB月套餐",
|
||
"package_type": "formal",
|
||
"price": 1500,
|
||
"quantity": 1
|
||
},
|
||
{
|
||
"package_id": 1002,
|
||
"package_name": "5GB加油包",
|
||
"package_type": "addon",
|
||
"price": 1000,
|
||
"quantity": 1
|
||
}
|
||
],
|
||
"paid_at": "2026-03-20T10:05:00Z",
|
||
"payment_method": "wechat",
|
||
"payment_status": 1,
|
||
"total_amount": 2500
|
||
}
|
||
}
|
||
|
||
字段说明：
|
||
data：
|
||
- completed_at：完成时间
|
||
- created_at：创建时间
|
||
- order_id：订单ID
|
||
- order_no：订单号
|
||
- packages：订单套餐列表
|
||
- paid_at：支付时间
|
||
- payment_method：支付方式
|
||
- payment_status：支付状态（0:待支付, 1:已支付, 2:已取消）
|
||
- total_amount：订单总金额（分）
|
||
|
||
data.packages[]：
|
||
- package_id：套餐ID
|
||
- package_name：套餐名称
|
||
- package_type：套餐类型（formal:正式套餐, addon:加油包）
|
||
- price：单价（分）
|
||
- quantity：数量
|
||
|
||
## 6.3 创建订单
|
||
|
||
URL：
|
||
POST /api/c/v1/orders/create
|
||
|
||
请求说明：
|
||
- 请求方式：POST
|
||
- 认证方式：Bearer Token（JWT）
|
||
- Content-Type：application/json
|
||
|
||
请求体参数：
|
||
- app_type（string，必填）- 应用类型（official_account:公众号, miniapp:小程序）
|
||
- identifier（string，必填）- 资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）
|
||
- package_ids（array<integer>，必填）- 套餐ID列表
|
||
|
||
请求示例：
|
||
{
|
||
"app_type": "miniapp",
|
||
"identifier": "1234567890",
|
||
"package_ids": [1001, 1002]
|
||
}
|
||
|
||
成功响应示例：
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"timestamp": "2026-03-20T10:00:00Z",
|
||
"data": {
|
||
"linked_package_info": {
|
||
"force_recharge_amount": 500,
|
||
"package_names": [
|
||
"10GB月套餐",
|
||
"5GB加油包"
|
||
],
|
||
"total_package_amount": 2500,
|
||
"wallet_credit": 300
|
||
},
|
||
"order": {
|
||
"created_at": "2026-03-20T10:00:00Z",
|
||
"order_id": 1,
|
||
"order_no": "ORD202603200001",
|
||
"payment_status": 0,
|
||
"total_amount": 2200
|
||
},
|
||
"order_type": "package",
|
||
"pay_config": {
|
||
"app_id": "wx1234567890",
|
||
"nonce_str": "randomstring",
|
||
"package": "prepay_id=wx201410272009395522657a690389285100",
|
||
"pay_sign": "SIGNATURE",
|
||
"sign_type": "RSA",
|
||
"timestamp": "1710928800"
|
||
},
|
||
"recharge": {
|
||
"amount": 500,
|
||
"auto_purchase_status": "enabled",
|
||
"recharge_id": 10,
|
||
"recharge_no": "RC202603200001",
|
||
"status": 0
|
||
}
|
||
}
|
||
}
|
||
|
||
字段说明：
|
||
data：
|
||
- linked_package_info：关联套餐信息
|
||
- order：订单信息
|
||
- order_type：订单类型（package:套餐订单, recharge:充值订单）
|
||
- pay_config：支付配置
|
||
- recharge：充值信息
|
||
|
||
data.linked_package_info：
|
||
- force_recharge_amount：强制充值金额（分）
|
||
- package_names：套餐名称列表
|
||
- total_package_amount：套餐总金额（分）
|
||
- wallet_credit：钱包抵扣金额（分）
|
||
|
||
data.order：
|
||
- created_at：创建时间
|
||
- order_id：订单ID
|
||
- order_no：订单号
|
||
- payment_status：支付状态（0:待支付, 1:已支付, 2:已取消）
|
||
- total_amount：订单总金额（分）
|
||
|
||
data.pay_config：
|
||
- app_id：应用ID
|
||
- nonce_str：随机字符串
|
||
- package：预支付参数
|
||
- pay_sign：支付签名
|
||
- sign_type：签名类型
|
||
- timestamp：时间戳
|
||
|
||
data.recharge：
|
||
- amount：充值金额（分）
|
||
- auto_purchase_status：自动购包状态
|
||
- recharge_id：充值ID
|
||
- recharge_no：充值单号
|
||
- status：状态（0:待支付, 1:已支付, 2:已关闭）
|
||
|
||
|
||
# 7. 实名
|
||
|
||
## 7.1 获取实名认证链接
|
||
|
||
URL：
|
||
GET /api/c/v1/realname/link
|
||
|
||
Query 参数：
|
||
- identifier（string，必填）- 资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）
|
||
- iccid（string，选填）- 物联网卡ICCID
|
||
|
||
请求说明：
|
||
- 请求方式：GET
|
||
- 认证方式：Bearer Token（JWT）
|
||
|
||
请求示例：
|
||
GET /api/c/v1/realname/link?identifier=1234567890&iccid=89860012345678901234
|
||
|
||
成功响应示例：
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"timestamp": "2026-03-20T10:00:00Z",
|
||
"data": {
|
||
"card_info": {
|
||
"iccid": "89860012345678901234",
|
||
"msisdn": "17000000000",
|
||
"virtual_no": "17100000000"
|
||
},
|
||
"expire_at": "2026-03-20T10:30:00Z",
|
||
"realname_mode": "gateway",
|
||
"realname_url": "https://example.com/realname/verify"
|
||
}
|
||
}
|
||
|
||
字段说明：
|
||
data：
|
||
- card_info：卡片简要信息
|
||
- expire_at：过期时间
|
||
- realname_mode：实名模式（none:无需实名, template:模板实名, gateway:网关实名）
|
||
- realname_url：实名链接
|
||
|
||
data.card_info：
|
||
- iccid：物联网卡ICCID
|
||
- msisdn：手机号
|
||
- virtual_no：虚拟号
|
||
|
||
|
||
# 8. 钱包
|
||
|
||
## 8.1 钱包详情
|
||
|
||
URL：
|
||
GET /api/c/v1/wallet/detail
|
||
|
||
Query 参数：
|
||
- identifier（string，必填）- 资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）
|
||
|
||
请求说明：
|
||
- 请求方式：GET
|
||
- 认证方式：Bearer Token（JWT）
|
||
|
||
请求示例：
|
||
GET /api/c/v1/wallet/detail?identifier=1234567890
|
||
|
||
成功响应示例：
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"timestamp": "2026-03-20T10:00:00Z",
|
||
"data": {
|
||
"balance": 10000,
|
||
"frozen_balance": 500,
|
||
"resource_id": 1,
|
||
"resource_type": "device",
|
||
"updated_at": "2026-03-20T10:00:00Z",
|
||
"wallet_id": 101
|
||
}
|
||
}
|
||
|
||
字段说明：
|
||
data：
|
||
- balance：可用余额（分）
|
||
- frozen_balance：冻结余额（分）
|
||
- resource_id：资源ID
|
||
- resource_type：资源类型（iot_card:物联网卡, device:设备）
|
||
- updated_at：更新时间
|
||
- wallet_id：钱包ID
|
||
|
||
## 8.2 创建充值订单
|
||
|
||
URL：
|
||
POST /api/c/v1/wallet/recharge
|
||
|
||
请求说明：
|
||
- 请求方式：POST
|
||
- 认证方式：Bearer Token（JWT）
|
||
- Content-Type：application/json
|
||
|
||
请求体参数：
|
||
- amount（integer，必填）- 充值金额（分）
|
||
- app_type（string，必填）- 应用类型（official_account:公众号, miniapp:小程序）
|
||
- identifier（string，必填）- 资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）
|
||
- payment_method（string，必填）- 支付方式（wechat:微信支付）
|
||
|
||
请求示例：
|
||
{
|
||
"amount": 1000,
|
||
"app_type": "miniapp",
|
||
"identifier": "1234567890",
|
||
"payment_method": "wechat"
|
||
}
|
||
|
||
成功响应示例：
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"timestamp": "2026-03-20T10:00:00Z",
|
||
"data": {
|
||
"pay_config": {
|
||
"app_id": "wx1234567890",
|
||
"nonce_str": "randomstring",
|
||
"package": "prepay_id=wx201410272009395522657a690389285100",
|
||
"pay_sign": "SIGNATURE",
|
||
"sign_type": "RSA",
|
||
"timestamp": "1710928800"
|
||
},
|
||
"recharge": {
|
||
"amount": 1000,
|
||
"recharge_id": 1,
|
||
"recharge_no": "RC202603200001",
|
||
"status": 0
|
||
}
|
||
}
|
||
}
|
||
|
||
字段说明：
|
||
data：
|
||
- pay_config：支付配置
|
||
- recharge：充值信息
|
||
|
||
data.pay_config：
|
||
- app_id：应用ID
|
||
- nonce_str：随机字符串
|
||
- package：预支付参数
|
||
- pay_sign：支付签名
|
||
- sign_type：签名类型
|
||
- timestamp：时间戳
|
||
|
||
data.recharge：
|
||
- amount：充值金额（分）
|
||
- recharge_id：充值ID
|
||
- recharge_no：充值单号
|
||
- status：状态（0:待支付, 1:已支付, 2:已关闭）
|
||
|
||
|
||
## 8.3 充值前校验
|
||
|
||
URL：
|
||
GET /api/c/v1/wallet/recharge-check
|
||
|
||
Query 参数：
|
||
- identifier（string，必填）- 资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）
|
||
|
||
请求说明：
|
||
- 请求方式：GET
|
||
- 认证方式：Bearer Token（JWT）
|
||
|
||
请求示例：
|
||
GET /api/c/v1/wallet/recharge-check?identifier=1234567890
|
||
|
||
成功响应示例：
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"timestamp": "2026-03-20T10:00:00Z",
|
||
"data": {
|
||
"force_recharge_amount": 1000,
|
||
"max_amount": 100000,
|
||
"message": "当前资产需先充值后再进行相关操作",
|
||
"min_amount": 100,
|
||
"need_force_recharge": true,
|
||
"trigger_type": "low_balance"
|
||
}
|
||
}
|
||
|
||
字段说明：
|
||
data：
|
||
- force_recharge_amount：强制充值金额（分）
|
||
- max_amount：最大充值金额（分）
|
||
- message：提示信息
|
||
- min_amount：最小充值金额（分）
|
||
- need_force_recharge：是否需要强制充值
|
||
- trigger_type：触发类型
|
||
|
||
## 8.4 充值记录列表
|
||
|
||
URL：
|
||
GET /api/c/v1/wallet/recharges
|
||
|
||
Query 参数：
|
||
- identifier（string，必填）- 资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）
|
||
- status（integer，选填）- 充值状态（0:待支付, 1:已支付, 2:已关闭）
|
||
- page（integer，必填）- 页码
|
||
- page_size（integer，必填）- 每页数量
|
||
|
||
请求说明：
|
||
- 请求方式：GET
|
||
- 认证方式：Bearer Token（JWT）
|
||
|
||
请求示例：
|
||
GET /api/c/v1/wallet/recharges?identifier=1234567890&status=1&page=1&page_size=10
|
||
|
||
成功响应示例：
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"timestamp": "2026-03-20T10:00:00Z",
|
||
"data": {
|
||
"items": [
|
||
{
|
||
"amount": 1000,
|
||
"auto_purchase_status": "enabled",
|
||
"created_at": "2026-03-20T10:00:00Z",
|
||
"payment_method": "wechat",
|
||
"recharge_id": 1,
|
||
"recharge_no": "RC202603200001",
|
||
"status": 1
|
||
}
|
||
],
|
||
"page": 1,
|
||
"page_size": 10,
|
||
"total": 1
|
||
}
|
||
}
|
||
|
||
字段说明：
|
||
data：
|
||
- items：充值记录列表
|
||
- page：页码
|
||
- page_size：每页数量
|
||
- total：总数
|
||
|
||
data.items[]：
|
||
- amount：充值金额（分）
|
||
- auto_purchase_status：自动购包状态
|
||
- created_at：创建时间
|
||
- payment_method：支付方式
|
||
- recharge_id：充值ID
|
||
- recharge_no：充值单号
|
||
- status：状态（0:待支付, 1:已支付, 2:已关闭）
|
||
|
||
|
||
## 8.5 钱包流水列表
|
||
|
||
URL：
|
||
GET /api/c/v1/wallet/transactions
|
||
|
||
Query 参数：
|
||
- identifier（string，必填）- 资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）
|
||
- transaction_type（string，选填）- 流水类型
|
||
- start_time（string，选填）- 开始时间
|
||
- end_time（string，选填）- 结束时间
|
||
- page（integer，必填）- 页码
|
||
- page_size（integer，必填）- 每页数量
|
||
|
||
请求说明：
|
||
- 请求方式：GET
|
||
- 认证方式：Bearer Token（JWT）
|
||
|
||
请求示例：
|
||
GET /api/c/v1/wallet/transactions?identifier=1234567890&transaction_type=recharge&start_time=2026-03-01T00:00:00Z&end_time=2026-03-20T23:59:59Z&page=1&page_size=10
|
||
|
||
成功响应示例：
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"timestamp": "2026-03-20T10:00:00Z",
|
||
"data": {
|
||
"items": [
|
||
{
|
||
"amount": 1000,
|
||
"balance_after": 5000,
|
||
"created_at": "2026-03-20T10:00:00Z",
|
||
"remark": "钱包充值",
|
||
"transaction_id": 1,
|
||
"type": "recharge"
|
||
}
|
||
],
|
||
"page": 1,
|
||
"page_size": 10,
|
||
"total": 1
|
||
}
|
||
}
|
||
|
||
字段说明：
|
||
data：
|
||
- items：流水列表
|
||
- page：页码
|
||
- page_size：每页数量
|
||
- total：总数
|
||
|
||
data.items[]：
|
||
- amount：变动金额（分）
|
||
- balance_after：变动后余额（分）
|
||
- created_at：创建时间
|
||
- remark：备注
|
||
- transaction_id：流水ID
|
||
- type：流水类型
|