# BaseUrl: https://cmp-api.boss160.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

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

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：流水类型
