# C 端所需接口文档

## 1. 通用约定

- 测试环境：`https://cmp-api.boss160.cn`
- 鉴权：除特别说明外，所有接口都需要登录后的 JWT。

```http
Authorization: Bearer <token>
Content-Type: application/json
```

- `identifier`：资产标识符，可传 SN、IMEI、虚拟号、ICCID 或 MSISDN，长度 1～50。
- 金额单位：分。页面展示时转换为元，提交时仍传整数分。
- 成功响应：`code = 0`。
- 错误响应：`400` 参数错误、`401` 未认证或过期、`403` 无权访问、`500` 服务端错误。

通用成功响应格式：

```json
{
  "code": 0,
  "data": {},
  "msg": "success",
  "timestamp": "2026-07-27T10:00:00+08:00"
}
```

错误响应格式：

```json
{
  "code": 1001,
  "data": {},
  "msg": "参数验证失败",
  "timestamp": "2026-07-27T10:00:00+08:00"
}
```

## 2. 接口清单

| 用途 | 方法 | 路径 |
| --- | --- | --- |
| 获取资产信息 | GET | `/api/c/v1/asset/info` |
| 充值前校验 | GET | `/api/c/v1/wallet/recharge-check` |
| 创建套餐订单 | POST | `/api/c/v1/orders/create` |
| 创建充值订单 | POST | `/api/c/v1/wallet/recharge` |
| 订单列表 | GET | `/api/c/v1/orders` |
| 订单详情 | GET | `/api/c/v1/orders/{id}` |

## 3. 获取资产信息

### 请求

```http
GET /api/c/v1/asset/info?identifier=1234567890
```

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `identifier` | string | 是 | 资产标识符，1～50 个字符 |

### `data` 关键返回字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `asset_id` | integer | 资产 ID |
| `asset_type` | string | `card` 卡、`device` 设备 |
| `identifier` | string | 当前资产标识符 |
| `iccid` / `msisdn` | string | 卡 ICCID / 手机号 |
| `sn` / `imei` / `virtual_no` | string | 设备序列号 / IMEI / 虚拟号 |
| `device_name` / `device_model` | string | 设备名称 / 型号 |
| `carrier_name` / `carrier_type` | string | 运营商名称 / 类型（`CMCC`、`CUCC`、`CTCC`、`CBN`） |
| `status` / `status_name` | integer / string | 资产归属状态：`1` 在库、`2` 已分销；卡沿用卡状态枚举 |
| `activation_status` / `activation_status_name` | integer / string | 激活状态：`0` 未激活、`1` 已激活 |
| `network_status` / `network_status_name` | integer / string | 网络状态：`0` 停机、`1` 开机 |
| `real_name_status` / `real_name_status_name` | integer / string | 实名状态：`0` 未实名、`1` 已实名 |
| `realname_policy` | string | 实名策略：`none`、`before_order`、`after_order` |
| `effective_realname_policy` | string | 当前实际生效的实名策略 |
| `realname_required` | boolean | 当前资产是否需要实名 |
| `allowed_payment_methods` | string[] | 允许的支付方式：`wallet`、`wechat`、`alipay` |
| `wallet_balance` | integer | 钱包余额，单位为分 |
| `current_package_id` | integer | 当前主套餐 ID；无套餐时为 `0`，可用于续费 |
| `current_package` | string | 当前套餐名称，无套餐时为空 |
| `current_package_activated_at` | datetime / null | 当前主套餐开始时间 |
| `current_package_expires_at` | datetime / null | 当前主套餐到期时间 |
| `estimated_final_expires_at` | datetime / null | 预计最终到期时间 |
| `days_until_final_expiry` | integer/null | 距预计最终到期的上海自然日天数 |
| `expiry_estimate_status` | string | `exact` 精确、`waiting_activation` 待激活、`none` 无套餐、`invalid_data` 数据异常 |
| `is_expiring` | boolean | 是否临期（精确推算且剩余 0～15 天） |
| `enable_virtual_data` | boolean | 当前主套餐是否启用虚流量 |
| `real_total_mb` / `real_used_mb` | integer | 真实总量 / 真实已用量，单位 MB |
| `virtual_total_mb` / `virtual_used_mb` | integer / number | 业务停机阈值 / 展示已用量，单位 MB |
| `reduction_pct` | number | 展示增幅比例：`real_total_mb / virtual_total_mb - 1` |
| `cards` | object[] | 设备绑定卡列表，包含 ICCID、MSISDN、网络状态、实名状态、插槽位置等 |
| `device_realtime` | object/null | 设备实时信息，包含在线状态、电量、信号、WiFi、客户端数等 |

页面流量展示建议：总量使用 `real_total_mb`；已用量在 `enable_virtual_data = true` 时使用 `virtual_used_mb`，否则使用 `real_used_mb`。

## 4. 充值前校验

### 请求

```http
GET /api/c/v1/wallet/recharge-check?identifier=1234567890
```

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `identifier` | string | 是 | 资产标识符 |

### `data` 返回字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `allowed_payment_methods` | string[]/null | 当前允许的支付方式：`wallet`、`wechat`、`alipay` |
| `need_force_recharge` | boolean | 是否必须先完成强制充值 |
| `force_recharge_amount` | integer | 强制充值金额，单位为分 |
| `min_amount` | integer | 最小充值金额，单位为分 |
| `max_amount` | integer | 最大充值金额，单位为分 |
| `message` | string | 页面提示信息 |
| `trigger_type` | string | 强制充值触发类型 |

## 5. 创建套餐订单

### 请求

```http
POST /api/c/v1/orders/create
```

```json
{
  "identifier": "1234567890",
  "package_ids": [1001, 1002],
  "payment_method": "wechat",
  "app_type": "miniapp"
}
```

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `identifier` | string | 是 | 资产标识符 |
| `package_ids` | integer[] | 是 | 套餐 ID 列表 |
| `payment_method` | string | 是 | `wallet`、`wechat`、`alipay` |
| `app_type` | string | 微信支付时是 | `official_account` 公众号、`miniapp` 小程序 |

### `data` 返回字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `idempotent` | boolean | 是否返回了已存在的待支付订单 |
| `order_type` | string | `package` 套餐订单、`recharge` 充值订单 |
| `order` | object | 订单信息，见下表 |
| `linked_package_info` | object | 关联套餐和强制充值信息 |
| `recharge` | object/null | 自动充值信息 |
| `pay_config` | object/null | 微信支付参数 |
| `payment_link` | object/null | 支付宝或其他网页支付链接 |

`order` 主要字段：`order_id`、`order_no`、`created_at`、`payment_method`、`payment_status`、`payment_status_name`、`total_amount`。

- `payment_status`：`1` 待支付、`2` 已支付、`3` 已取消、`4` 已退款。
- `linked_package_info`：`force_recharge_amount`、`package_names`、`total_package_amount`、`wallet_credit`，金额均为分。
- `recharge`：`recharge_id`、`recharge_no`、`amount`、`status`、`status_name`、`auto_purchase_status`。
- `pay_config`：`app_id`、`nonce_str`、`package`、`pay_sign`、`sign_type`、`timestamp`。
- `payment_link`：`copy_link`、`qr_link`、`payment_no`、`pay_expire_at`。

## 6. 创建充值订单

### 请求

```http
POST /api/c/v1/wallet/recharge
```

```json
{
  "amount": 1000,
  "identifier": "1234567890",
  "payment_method": "wechat",
  "app_type": "miniapp"
}
```

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `amount` | integer | 是 | 充值金额，1～10000000 分 |
| `identifier` | string | 是 | 资产标识符 |
| `payment_method` | string | 是 | `wechat` 微信支付、`alipay` 支付宝 |
| `app_type` | string | 微信支付时是 | `official_account` 或 `miniapp` |

### `data` 返回字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `recharge` | object | 充值信息：`recharge_id`、`recharge_no`、`amount`、`status` |
| `pay_config` | object/null | 微信支付参数：`app_id`、`nonce_str`、`package`、`pay_sign`、`sign_type`、`timestamp` |
| `payment_link` | object/null | 支付链接：`copy_link`、`qr_link`、`payment_no`、`pay_expire_at` |

`recharge.status`：`0` 待支付、`1` 已支付、`2` 已关闭。

## 7. 订单列表

### 请求

```http
GET /api/c/v1/orders?identifier=1234567890&page=1&page_size=10
```

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `identifier` | string | 是 | 资产标识符 |
| `payment_status` | integer | 否 | `1` 待支付、`2` 已支付、`3` 已取消、`4` 已退款 |
| `page` | integer | 是 | 页码，从 1 开始 |
| `page_size` | integer | 是 | 每页数量，1～100 |

### `data` 返回字段

```json
{
  "items": [],
  "page": 1,
  "size": 10,
  "total": 0
}
```

`items[]` 字段：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `order_id` / `order_no` | integer / string | 订单 ID / 订单号 |
| `asset_id` / `asset_type` | integer / string | 资产 ID / `card` 或 `device` |
| `asset_identifier` | string | 下单时资产标识快照；设备优先虚拟号，其次 IMEI |
| `package_ids` / `package_names` | array | 套餐 ID / 名称列表 |
| `payment_method` | string | `wallet`、`wechat`、`alipay` |
| `payment_status` / `payment_status_name` | integer / string | 支付状态及中文名称 |
| `total_amount` | integer | 订单总金额，单位为分 |
| `created_at` | string | 创建时间 |

## 8. 订单详情

### 请求

```http
GET /api/c/v1/orders/{id}
```

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | integer | 是 | 订单 ID，放在 URL 路径中 |

### `data` 返回字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `order_id` / `order_no` | integer / string | 订单 ID / 订单号 |
| `asset_id` / `asset_type` | integer / string | 资产 ID / `card` 或 `device` |
| `asset_identifier` | string | 下单时资产标识快照 |
| `packages` | object[] | 订单套餐明细 |
| `payment_method` | string | 支付方式 |
| `payment_status` / `payment_status_name` | integer / string | 支付状态及中文名称 |
| `total_amount` | integer | 订单总金额，单位为分 |
| `created_at` | string | 创建时间 |
| `paid_at` | string/null | 支付时间 |
| `completed_at` | string/null | 完成时间 |

`packages[]` 字段：`package_id`、`package_name`、`package_type`（`formal` 正式套餐、`addon` 加油包）、`price`（分）、`quantity`。

## 9. 前端调用流程

1. 登录后保存 JWT，后续请求统一携带 `Authorization: Bearer <token>`。
2. 进入资产页面调用资产信息接口，并使用返回的 `allowed_payment_methods` 渲染支付方式。
3. 充值先调用充值前校验；若 `need_force_recharge = true`，使用后端返回的强制充值金额和提示。
4. 套餐购买或续费调用创建订单接口，`package_ids` 使用当前资产的 `current_package_id` 或历史订单的 `package_ids`。
5. 充值调用创建充值订单接口。微信支付时必须传 `app_type`。
6. 页面展示支付链接或支付参数后，支付结果通过订单详情等查询接口确认；不要仅根据前端跳转结果判断已支付。