# 接口详情
本文档说明 OpenAPI 当前开放的接口。除心跳接口外，请求都需要携带通用签名参数。
## 通用请求参数
| 参数名 | 类型 | 必需 | 描述 | 示例 |
| --- | --- | --- | --- | --- |
| `access_key` | string | 是 | 访问密钥 | `ak_test123` |
| `timestamp` | string | 是 | Unix 时间戳，单位秒 | `1730619000` |
| `nonce` | string | 是 | 随机字符串，建议每次请求唯一 | `test123` |
| `signature` | string | 是 | HMAC-SHA256 签名 | `abc123def456` |
GET 接口使用 Query String 传参。POST 接口支持 `application/json` 和 `application/x-www-form-urlencoded`。
## 通用响应结构
成功响应：
```json
{
"code": "OK",
"msg": "ok",
"data": {},
"ok": true
}
```
失败响应：
```json
{
"code": "InvalidParams",
"msg": "提交的参数不符合要求",
"ok": false
}
```
常见错误码：
| code | HTTP 状态码 | 描述 |
| --- | --- | --- |
| `InvalidParams` | 400 | 参数缺失、格式错误或资源编号不存在 |
| `BadRequest` | 400 | 业务规则不满足，例如需要先充值后实名 |
| `AlreadyVerified` | 400 | 已完成实名认证 |
| `PermissionDenied` | 403 | 没有操作权限 |
| `Forbidden` | 403 | 无法访问当前资源 |
| `InternalError` | 500 | 系统内部错误或上游接口异常 |
---
## 1. 心跳检测
检测服务是否正常运行，返回服务器当前时间。
**请求信息**
| 项 | 值 |
| --- | --- |
| 方法 | `GET` |
| 路径 | `/api/v1/heartbeat` |
| 参数 | 通用签名参数 |
**请求示例**
```bash
GET /api/v1/heartbeat?access_key=ak_test123×tamp=1730619000&nonce=test123&signature=abc123def456
Host: your-domain.com
```
**响应示例**
```text
2026-05-03T16:30:00+08:00
```
---
## 2. 获取可对接套餐列表
查询当前 API 账号可对接的套餐列表。
**请求信息**
| 项 | 值 |
| --- | --- |
| 方法 | `GET` |
| 路径 | `/api/v1/packages` |
| 参数格式 | Query String |
**业务参数**
| 参数名 | 类型 | 必需 | 描述 | 示例 |
| --- | --- | --- | --- | --- |
| `package_code` | string | 否 | 套餐编码，支持模糊筛选 | `pkg_d4k9...` |
**请求示例**
```bash
GET /api/v1/packages?package_code=pkg_d4k9...&access_key=ak_test123×tamp=1730619000&nonce=test123&signature=abc123def456
Host: your-domain.com
```
**响应示例**
```json
{
"code": "OK",
"msg": "ok",
"data": [
{
"id": 100,
"upstream_package_code": "PKG001",
"package_code": "pkg_d4k9...",
"name": "联通月包10G",
"description": "月租套餐",
"launched": true,
"operators": ["CUCC"],
"weight": 100,
"price": 19.9,
"cost": 15,
"low_price": 0,
"high_price": 99,
"total_flow": 10240,
"can_buy_next_month": true,
"type": "0",
"buy_limit": 0,
"day": 2,
"cycle": 1,
"unlimited": false,
"daytime": 1,
"add_time": 2,
"flow_slicing_strategy": 0,
"flow_slicing_count": 0,
"series_name": "联通标准系列"
}
],
"ok": true
}
```
**说明**
- 仅返回当前 API 账号有权限对接的已上架套餐。
- `total_flow` 返回展示流量。
- `series_name` 只返回系列名称，不返回完整系列配置。
- `package_code` 为空时返回全部可对接套餐。
**data 数组字段说明**
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | number | 套餐 ID。该值是当前系统内套餐的唯一标识，仅用于展示或排查，不作为下单参数。 |
| `upstream_package_code` | string | 上游套餐编码。仅用于识别上游套餐，不作为下单参数。 |
| `package_code` | string | 套餐编码。下单时传 `package_code`。 |
| `name` | string | 套餐名称。用于展示给用户。 |
| `description` | string | 套餐描述或套餐备注。可能为空字符串。 |
| `launched` | bool | 是否已上架。`true` 表示当前套餐可对接、可下单。 |
| `operators` | string[] | 套餐支持的运营商列表。返回的是运营商编码数组。 |
| `weight` | number | 套餐权重。通常用于前端排序，值越大通常越靠前。 |
| `price` | number | 套餐销售价。单位为元。 |
| `cost` | number | 套餐成本价。单位为元。 |
| `low_price` | number | 套餐允许的最低售价。单位为元。 |
| `high_price` | number | 套餐允许的最高售价。单位为元。 |
| `total_flow` | number | 套餐总流量，单位为 MB。 |
| `can_buy_next_month` | bool | 是否支持购买“次月生效”套餐。`true` 表示下单时可传 `strategy=2`。 |
| `type` | string | 套餐类型。`"0"` 表示基础套餐，`"1"` 表示加油包。 |
| `buy_limit` | number | 购买次数限制。`0` 一般表示不限制；大于 `0` 表示单个对象只能购买指定次数。 |
| `day` | number | 套餐结算周期类型。`1`=按天，`2`=按月，`3`=每月 26 号结算。 |
| `cycle` | number | 套餐周期数量。需要结合 `day` 一起理解。比如 `day=2` 且 `cycle=1` 表示 1 个月。 |
| `unlimited` | bool | 是否为无限流量套餐。`true` 表示无限流量，`false` 表示非无限流量。 |
| `daytime` | number | 套餐结算时间规则。`1`=在结算日当天结束时失效，`2`=在结算日的订购时间点失效。 |
| `add_time` | number | 套餐时间叠加规则。`1`=无限叠加时间，`2`=立即生效，`3`=前一个套餐失效。 |
| `flow_slicing_strategy` | number | 流量切片策略。`0`=不切片，`1`=按结算日自动切片，`2`=按平均值自动切片。 |
| `flow_slicing_count` | number | 流量切片数量。仅当 `flow_slicing_strategy=2` 时有实际意义；其它情况通常为 `0`。 |
| `series_name` | string | 套餐所属系列名称。当前开放接口只返回名称，不返回系列完整配置。 |
**operators 字段取值说明**
| 值 | 说明 |
| --- | --- |
| `CMCC` | 中国移动 |
| `CUCC` | 中国联通 |
| `CTCC` | 中国电信 |
| `CBNC` | 中国广电 |
**补充示例**
- `day=2`、`cycle=1`：表示 1 个月套餐。
- `day=1`、`cycle=30`：表示 30 天套餐。
- `can_buy_next_month=true`：下游下单时可以传 `strategy=2` 表示次月生效。
- `buy_limit=3`：表示同一个卡板或设备最多购买 3 次该套餐。
---
## 3. 卡板信息查询
查询指定卡板的流量、余额、状态和实名状态。
**请求信息**
| 项 | 值 |
| --- | --- |
| 方法 | `GET` |
| 路径 | `/api/v1/info` |
| 参数格式 | Query String |
**业务参数**
| 参数名 | 类型 | 必需 | 描述 | 示例 |
| --- | --- | --- | --- | --- |
| `card_no` | string | 是 | 卡板编号 | `CARD123456789` |
**请求示例**
```bash
GET /api/v1/info?card_no=CARD123456789&access_key=ak_test123×tamp=1730619000&nonce=test123&signature=abc123def456
Host: your-domain.com
```
**响应示例**
```json
{
"code": "OK",
"msg": "ok",
"data": {
"card_no": "CARD123456789",
"total_flow": 10240,
"used_flow": 5120,
"status": 2,
"official_real_name_verified": true,
"balance": "100.50",
"delete_on": "2026-06-01T00:00:00+08:00"
},
"ok": true
}
```
**data 字段说明**
| 字段 | 类型 | 描述 |
| --- | --- | --- |
| `card_no` | string | 卡板编号 |
| `total_flow` | number | 可用总流量，单位 MB |
| `used_flow` | number | 已使用流量，单位 MB |
| `status` | int | 卡板状态码 |
| `official_real_name_verified` | bool | 是否官方实名 |
| `balance` | number | 余额 |
| `delete_on` | string | 当前在用套餐到期时间，可选 |
---
## 4. 获取卡板实名链接
获取指定卡板的官方实名链接。
**请求信息**
| 项 | 值 |
| --- | --- |
| 方法 | `GET` |
| 路径 | `/api/v1/real-name-url` |
| 参数格式 | Query String |
**业务参数**
| 参数名 | 类型 | 必需 | 描述 | 示例 |
| --- | --- | --- | --- | --- |
| `card_no` | string | 是 | 卡板编号 | `CARD123456789` |
**请求示例**
```bash
GET /api/v1/real-name-url?card_no=CARD123456789&access_key=ak_test123×tamp=1730619000&nonce=test123&signature=abc123def456
Host: your-domain.com
```
**成功响应**
```json
{
"code": "OK",
"msg": "ok",
"data": "https://example.com/real-name?card_no=CARD123456789",
"ok": true
}
```
**业务规则**
| 场景 | 返回 |
| --- | --- |
| 卡板已官方实名 | `AlreadyVerified`，`msg` 为 `当前卡板已完成实名认证` |
| 套餐系列配置为先充值后实名，且卡板没有已支付订单 | `BadRequest`，`msg` 为 `卡板需要先充值后实名` |
| 套餐系列不存在 | `DataMissing` |
| 上游获取实名链接失败 | `InternalError`，`msg` 带具体失败原因 |
---
## 5. 刷新卡板流量
主动刷新指定卡板的最新流量信息，成功后仅返回成功状态。
**请求信息**
| 项 | 值 |
| --- | --- |
| 方法 | `POST` |
| 路径 | `/api/v1/refresh-flow` |
| 参数格式 | JSON 或 Form |
**业务参数**
| 参数名 | 类型 | 必需 | 描述 | 示例 |
| --- | --- | --- | --- | --- |
| `card_no` | string | 是 | 卡板编号 | `CARD123456789` |
**请求示例**
```json
{
"card_no": "CARD123456789",
"access_key": "ak_test123",
"timestamp": "1730619000",
"nonce": "test123",
"signature": "abc123def456"
}
```
**成功响应**
```json
{
"code": "OK",
"msg": "ok",
"ok": true
}
```
---
## 6. 卡板复机
对指定卡板执行复机操作。
**请求信息**
| 项 | 值 |
| --- | --- |
| 方法 | `POST` |
| 路径 | `/api/v1/start` |
| 参数格式 | JSON 或 Form |
**业务参数**
| 参数名 | 类型 | 必需 | 描述 | 示例 |
| --- | --- | --- | --- | --- |
| `card_no` | string | 是 | 卡板编号 | `CARD123456789` |
**权限要求**
API 账号必须具有停复机权限。
**成功响应**
```json
{
"code": "OK",
"msg": "ok",
"data": true,
"ok": true
}
```
---
## 7. 卡板停机
对指定卡板执行停机操作。
**请求信息**
| 项 | 值 |
| --- | --- |
| 方法 | `POST` |
| 路径 | `/api/v1/stop` |
| 参数格式 | JSON 或 Form |
**业务参数**
| 参数名 | 类型 | 必需 | 描述 | 示例 |
| --- | --- | --- | --- | --- |
| `card_no` | string | 是 | 卡板编号 | `CARD123456789` |
**权限要求**
API 账号必须具有停复机权限。
**成功响应**
```json
{
"code": "OK",
"msg": "ok",
"data": true,
"ok": true
}
```
---
## 8. 卡板套餐订购
为指定卡板订购套餐。
**请求信息**
| 项 | 值 |
| --- | --- |
| 方法 | `POST` |
| 路径 | `/api/v1/orders` |
| 参数格式 | JSON 或 Form |
**业务参数**
| 参数名 | 类型 | 必需 | 描述 | 示例 |
| --- | --- | --- | --- | --- |
| `card_no` | string | 是 | 卡板编号 | `CARD123456789` |
| `package_code` | string | 是 | 套餐编码 | `pkg_d4k9...` |
| `strategy` | uint8 | 是 | 生效策略，`1`=本月生效，`2`=次月生效 | `1` |
**请求示例**
```json
{
"card_no": "CARD123456789",
"package_code": "pkg_d4k9...",
"strategy": 1,
"access_key": "ak_test123",
"timestamp": "1730619000",
"nonce": "test123",
"signature": "abc123def456"
}
```
**成功响应**
```json
{
"code": "OK",
"msg": "ok",
"data": {
"order_no": "ORD202605030001"
},
"ok": true
}
```
**业务规则**
- 当前使用余额支付。
- 余额不足、套餐不可用、卡板状态不满足时会返回失败。
- `strategy=1` 表示本月生效，`strategy=2` 表示次月生效。
---
## 9. 获取移动 Token
根据渠道 ID 获取移动下游实时 token。
**请求信息**
| 项 | 值 |
| --- | --- |
| 方法 | `POST` |
| 路径 | `/api/v1/token` |
| 参数格式 | JSON 或 Form |
**业务参数**
| 参数名 | 类型 | 必需 | 描述 | 示例 |
| --- | --- | --- | --- | --- |
| `channel_id` | uint | 是 | 渠道 ID，仅支持移动渠道 | `1` |
**请求示例**
```json
{
"channel_id": 1,
"access_key": "ak_test123",
"timestamp": "1730619000",
"nonce": "test123",
"signature": "abc123def456"
}
```
**成功响应**
```json
{
"code": "OK",
"msg": "ok",
"data": {
"channel_id": 1,
"token": "3d7d94df3cf1e7942efe408ee141cca6"
},
"ok": true
}
```
**业务规则**
- 仅支持移动渠道。
- token 为实时获取结果，下游不应长期缓存。
- 渠道未配置移动 token 时会返回参数错误。
---
## 10. 设备信息查询
查询指定设备信息，包括设备基础信息、流量信息和卡槽信息。
**请求信息**
| 项 | 值 |
| --- | --- |
| 方法 | `GET` |
| 路径 | `/api/v1/device/info` |
| 参数格式 | Query String |
**业务参数**
| 参数名 | 类型 | 必需 | 描述 | 示例 |
| --- | --- | --- | --- | --- |
| `device_no` | string | 是 | 设备编号 | `DEVICE123456789` |
**请求示例**
```bash
GET /api/v1/device/info?device_no=DEVICE123456789&access_key=ak_test123×tamp=1730619000&nonce=test123&signature=abc123def456
Host: your-domain.com
```
**响应示例**
```json
{
"code": "OK",
"msg": "ok",
"data": {
"device_no": "DEVICE123456789",
"balance": "50.00",
"signal": "4",
"electricity": "85",
"device_conn_num": 3,
"wifi_status": 1,
"hide_wifi": false,
"wifi_name": "TCZK-5G",
"used_flow": 1024.5,
"total_flow": 20480,
"delete_on": "2026-06-01T00:00:00+08:00",
"card_slots": [
{
"slot_code": "1",
"card_no": "8986001234567890123",
"official_real_name_verified": true,
"card_status": 2,
"is_main_slot": true,
"is_current_slot": true
}
]
},
"ok": true
}
```
**data 字段说明**
| 字段 | 类型 | 描述 |
| --- | --- | --- |
| `device_no` | string | 设备编号 |
| `balance` | number | 设备余额 |
| `signal` | string | 信号强度 |
| `electricity` | string | 电量 |
| `device_conn_num` | int | 当前设备连接数 |
| `wifi_status` | int | WiFi 状态 |
| `hide_wifi` | bool | 是否隐藏 WiFi |
| `wifi_name` | string | WiFi 名称 |
| `used_flow` | number | 设备虚拟已用流量，单位 MB |
| `total_flow` | number | 设备虚拟可用总流量，单位 MB |
| `delete_on` | string | 当前在用套餐到期时间，可选 |
| `card_slots` | array | 卡槽列表 |
**card_slots 字段说明**
| 字段 | 类型 | 描述 |
| --- | --- | --- |
| `slot_code` | string | 卡槽编号 |
| `card_no` | string | 卡号 |
| `official_real_name_verified` | bool | 当前卡槽卡板是否官方实名 |
| `card_status` | int | 卡板状态码 |
| `is_main_slot` | bool | 是否主卡槽 |
| `is_current_slot` | bool | 是否当前在用卡槽 |
---
## 11. 获取设备实名链接
获取指定设备所有卡槽的官方实名链接列表。
**请求信息**
| 项 | 值 |
| --- | --- |
| 方法 | `GET` |
| 路径 | `/api/v1/device/real-name-url` |
| 参数格式 | Query String |
**业务参数**
| 参数名 | 类型 | 必需 | 描述 | 示例 |
| --- | --- | --- | --- | --- |
| `device_no` | string | 是 | 设备编号 | `DEVICE123456789` |
**请求示例**
```bash
GET /api/v1/device/real-name-url?device_no=DEVICE123456789&access_key=ak_test123×tamp=1730619000&nonce=test123&signature=abc123def456
Host: your-domain.com
```
**成功响应**
```json
{
"code": "OK",
"msg": "ok",
"data": [
{
"slot_code": "1",
"card_no": "8986001234567890123",
"official_real_name_verified": false,
"is_main_slot": true,
"is_current_slot": true,
"url": "https://example.com/real-name?device_no=DEVICE123456789&slot=1"
},
{
"slot_code": "2",
"card_no": "8986001234567890124",
"official_real_name_verified": true,
"is_main_slot": false,
"is_current_slot": false,
"url": ""
}
],
"ok": true
}
```
**data 子字段说明**
| 字段 | 类型 | 描述 |
| --- | --- | --- |
| `slot_code` | string | 卡槽编号，按卡槽编号排序返回 |
| `card_no` | string | 卡号 |
| `official_real_name_verified` | bool | 当前卡槽卡板是否已官方实名 |
| `is_main_slot` | bool | 是否主卡槽 |
| `is_current_slot` | bool | 是否当前在用卡槽 |
| `url` | string | 实名链接；已实名或当前卡槽不可实名时为空字符串 |
| `msg` | string | 当前卡槽不可实名的原因，可选 |
**业务规则**
| 场景 | 返回 |
| --- | --- |
| 当前卡槽已官方实名 | 该卡槽 `official_real_name_verified=true`，`url=""` |
| 套餐系列要求先充值后实名，且设备或卡槽没有已支付订单 | 该卡槽 `url=""`，`msg` 为 `设备需要先充值后实名` |
| 当前设备生效套餐为单网套餐，副卡槽不可实名 | 副卡槽 `url=""`，`msg` 为 `当前是单网套餐，不允许实名副卡槽` |
| 设备卡板或卡槽配置异常 | `InternalError` |
**说明**
- 单网套餐只允许主卡槽实名。
- 如果卡槽配置为上游实名链接，系统会优先通过设备号获取上游设备实名链接；取不到时回退到卡板实名链接逻辑。
- 调用方只需要传 `device_no`，不需要传 `slot_code`。
---
## 12. 设备套餐订购
为指定设备订购套餐。
**请求信息**
| 项 | 值 |
| --- | --- |
| 方法 | `POST` |
| 路径 | `/api/v1/device/orders` |
| 参数格式 | JSON 或 Form |
**业务参数**
| 参数名 | 类型 | 必需 | 描述 | 示例 |
| --- | --- | --- | --- | --- |
| `device_no` | string | 是 | 设备编号 | `DEVICE123456789` |
| `package_code` | string | 是 | 套餐编码 | `pkg_d4k9...` |
| `strategy` | uint8 | 是 | 生效策略，`1`=本月生效，`2`=次月生效 | `1` |
**请求示例**
```json
{
"device_no": "DEVICE123456789",
"package_code": "pkg_d4k9...",
"strategy": 1,
"access_key": "ak_test123",
"timestamp": "1730619000",
"nonce": "test123",
"signature": "abc123def456"
}
```
**成功响应**
```json
{
"code": "OK",
"msg": "ok",
"data": {
"order_no": "ORD202605030002"
},
"ok": true
}
```
**业务规则**
- 当前使用余额支付。
- 余额不足、套餐不可用、设备状态不满足时会返回失败。
- `strategy=1` 表示本月生效，`strategy=2` 表示次月生效。
---
## 13. 设备操作指令
统一执行设备相关指令。
**请求信息**
| 项 | 值 |
| --- | --- |
| 方法 | `POST` |
| 路径 | `/api/v1/device/command` |
| 参数格式 | JSON 或 Form |
**基础业务参数**
| 参数名 | 类型 | 必需 | 描述 | 示例 |
| --- | --- | --- | --- | --- |
| `device_no` | string | 是 | 设备编号 | `DEVICE123456789` |
| `command` | string | 是 | 指令名称 | `restart` |
**command 明细**
| command | 描述 | 额外参数 |
| --- | --- | --- |
| `restart` | 设备启用/复机 | 无 |
| `shutdown` | 设备禁用/停机 | 无 |
| `restart_device` | 重启设备 | 无 |
| `factory_reset` | 恢复出厂设置 | 无 |
| `switch_network` | 切换设备在用卡槽 | `slot_code` 必填 |
| `set_wifi_visible` | 设置 WiFi 是否隐藏 | `hidden` 必填，bool，`true`=隐藏，`false`=显示 |
| `update_wifi` | 修改 WiFi 名称和密码 | `wifi_name`、`wifi_password` 必填 |
**请求示例：设备复机**
```json
{
"device_no": "DEVICE123456789",
"command": "restart",
"access_key": "ak_test123",
"timestamp": "1730619000",
"nonce": "test123",
"signature": "abc123def456"
}
```
**请求示例：切网**
```json
{
"device_no": "DEVICE123456789",
"command": "switch_network",
"slot_code": "1",
"access_key": "ak_test123",
"timestamp": "1730619000",
"nonce": "test123",
"signature": "abc123def456"
}
```
**请求示例：修改 WiFi**
```json
{
"device_no": "DEVICE123456789",
"command": "update_wifi",
"wifi_name": "TCZK-5G",
"wifi_password": "12345678",
"access_key": "ak_test123",
"timestamp": "1730619000",
"nonce": "test123",
"signature": "abc123def456"
}
```
**成功响应**
```json
{
"code": "OK",
"msg": "ok",
"data": true,
"ok": true
}
```
**业务规则**
- `restart`、`shutdown` 需要 API 账号具有停复机权限。
- `switch_network` 的 `slot_code` 必须存在于设备所属渠道的卡槽配置中。
- `set_wifi_visible` 必须传 `hidden`。
- `update_wifi` 必须同时传 `wifi_name` 和 `wifi_password`。