device-voice-h5/docs/所需接口文档/new-api.md

C 端所需接口文档

1. 通用约定

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

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

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

通用成功响应格式：

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

错误响应格式：

{
  "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. 获取资产信息

请求

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. 充值前校验

请求

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. 创建套餐订单

请求

POST /api/c/v1/orders/create

{
  "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. 创建充值订单

请求

POST /api/c/v1/wallet/recharge

{
  "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. 订单列表

请求

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 返回字段

{
  "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. 订单详情

请求

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. 页面展示支付链接或支付参数后，支付结果通过订单详情等查询接口确认；不要仅根据前端跳转结果判断已支付。