# 接口详情
## 1. 心跳检测
检测服务是否正常运行，返回服务器当前时间。
**请求信息**
- **方法**: `GET`
- **路径**: `/api/v1/heartbeat`
- **参数**: 仅需认证参数
**请求示例**:
```bash
GET /api/v1/heartbeat?access_key=ak_test123×tamp=1730619000&nonce=test123&signature=abc123def456
Host: your-domain.com
```
**响应信息**:
- **状态码**: `200 OK`
- **Content-Type**: `text/plain`
- **响应体**: ISO 8601 格式时间字符串
**响应示例**:
```
2024-11-03T16:30:00Z
```
**使用场景**:
- 服务健康检查
- 网络连通性测试
- 客户端初始化验证
---
## 2. 卡板信息查询
查询指定卡板的详细信息，包括流量、余额、状态等。
**请求信息**
- **方法**: `GET`
- **路径**: `/api/v1/info`
- **参数格式**: Query String (URL参数)
**请求参数**:
| 参数名 | 类型 | 必需 | 描述 | 示例 |
|-----------|--------|----|------|-----------------|
| `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
```
**响应信息**:
- **状态码**: `200 OK` / `400 Bad Request` / `404 Not Found`
- **Content-Type**: `application/json`
**响应结构**:
```json
{
"code": "OK",
"msg": "ok",
"data": {
"total_flow": 10737418240,
"used_flow": 5368709120,
"official_real_name_verified": true,
"balance": "100.50",
"status": 2
},
"ok": true
}
```
**字段说明**:
| 字段 | 类型 | 描述 | 示例 |
|-------------------------------|--------|-------------|-----------------|
| `total_flow` | int64 | 总流量（单位：MB） | 10240 |
| `used_flow` | int64 | 已使用流量（单位：MB） | 5120 |
| `status` | int | 卡板状态 | 2 |
| `official_real_name_verified` | bool | 是否实名认证 | true |
| `balance` | number | 账户余额 | 100.50 |
| `card_no` | string | 卡板编号 | "CARD123456789" |
| `delete_on` | string | 当点套餐失效时间（可选） | "2025-01-15T08:30:00Z" |
**卡板状态对照表**:
| 状态码 | 状态名称 | 描述 |
|-----|------|------------------|
| 1 | 待激活 | 卡板尚未激活，需要先激活才能使用 |
| 2 | 已激活 | 卡板正常使用中，可进行正常操作 |
| 3 | 机卡分离 | 卡板与设备分离，需要重新绑定 |
| 4 | 停机 | 卡板已停机，可申请复机 |
| 5 | 风险停机 | 因风险原因停机，需要人工处理 |
| 6 | 销户 | 卡板账户已注销 |
| 7 | 库存 | 卡板在库存中，未分配使用 |
| 8 | 其他 | 其他未知状态 |
| 9 | 可测试 | 卡板可进行测试操作 |
| 10 | 达量断网 | 流量用完导致断网 |
---
## 3. 卡板复机
对指定卡板执行复机操作，使其恢复正常服务。
**请求信息**
- **方法**: `POST`
- **路径**: `/api/v1/start`
- **支持格式**: `application/x-www-form-urlencoded` 或 `application/json`
**请求参数**:
| 参数名 | 类型 | 必需 | 描述 | 示例 |
|-----------|--------|----|------|-------------|
| `card_no` | string | ✅ | 卡板编号 | `123456789` |
**权限要求**:
- API账号必须具有停复机权限
- 卡板必须处于可复机状态
**请求示例**:
*使用 Form 格式:*
```bash
POST /api/v1/start
Host: 接口地址
Content-Type: application/x-www-form-urlencoded
access_key=ak_test123&card_no=CARD123456789×tamp=1730619000&nonce=test123&signature=abc123def456
```
*使用 JSON 格式:*
```bash
POST /api/v1/start
Host: 接口地址
Content-Type: application/json
{
"access_key": "ak_test123",
"card_no": "CARD123456789",
"timestamp": "1730619000",
"nonce": "test123",
"signature": "abc123def456"
}
```
**响应信息**:
- **状态码**: `200 OK` / `400 Bad Request` / `403 Forbidden`
- **Content-Type**: `application/json`
**成功响应**:
```json
{
"code": "OK",
"msg": "ok",
"data": true,
"ok": true
}
```
**失败响应示例**:
```json
{
"code": 403,
"message": "API账号已被禁用",
"data": null
}
```
**操作流程**:
1. 验证API权限
2. 检查卡板状态
3. 执行复机操作
4. 返回操作结果
---
## 4. 卡板停机
对指定卡板执行停机操作，暂停其服务。
**请求信息**
- **方法**: `POST`
- **路径**: `/api/v1/stop`
- **支持格式**: `application/x-www-form-urlencoded` 或 `application/json`
**请求参数**:
| 参数名 | 类型 | 必需 | 描述 | 示例 |
|-----------|--------|----|------|-----------------|
| `card_no` | string | ✅ | 卡板编号 | `CARD123456789` |
**权限要求**:
- API账号必须具有停复机权限
- 卡板必须处于可停机状态
**请求示例**:
*使用 Form 格式:*
```bash
POST /api/v1/stop
Host: 接口地址
Content-Type: application/x-www-form-urlencoded
access_key=ak_test123&card_no=CARD123456789×tamp=1730619000&nonce=test123&signature=abc123def456
```
*使用 JSON 格式:*
```bash
POST /api/v1/stop
Host: 接口地址
Content-Type: application/json
{
"access_key": "ak_test123",
"card_no": "CARD123456789",
"timestamp": "1730619000",
"nonce": "test123",
"signature": "abc123def456"
}
```
**响应信息**:
- **状态码**: `200 OK` / `400 Bad Request` / `403 Forbidden`
- **Content-Type**: `application/json`
**成功响应**:
```json
{
"code": "OK",
"msg": "ok",
"data": true,
"ok": true
}
```
**操作注意事项**:
- 停机操作会影响卡板的正常服务
- 建议在非高峰时段执行
- 操作后可能需要等待生效时间
---
## 5. 套餐订购
为指定卡板订购套餐服务。
**请求信息**
- **方法**: `POST`
- **路径**: `/api/v1/orders`
- **支持格式**: `application/x-www-form-urlencoded` 或 `application/json`
- **推荐格式**: `application/json`（推荐使用JSON格式，便于参数验证）
**请求参数**:
| 参数名 | 类型 | 必需 | 描述 | 取值范围 |
|--------------|--------|----|---------------|------------------|
| `card_no` | string | ✅ | 卡板编号 | 合法卡板编号 |
| `package_id` | uint | ✅ | 套餐ID | 正整数 |
| `strategy` | uint8 | ✅ | 生效策略 | 1=本月生效, 2=次月生效 |
| `access_key` | string | ✅ | 访问密钥 | 格式：ak_xxxxxxxxxx |
| `timestamp` | string | ✅ | Unix时间戳 | 10位数字 |
| `nonce` | string | ✅ | 随机字符串 | 8-128字符 |
| `signature` | string | ✅ | HMAC-SHA256签名 | 64位十六进制 |
**请求参数结构**:
*使用 JSON 格式 (推荐):*
```json
{
"card_no": "CARD123456789",
"package_id": 100,
"strategy": 1,
"access_key": "ak_test123",
"timestamp": "1730619000",
"nonce": "test123",
"signature": "abc123def456"
}
```
*使用 Form 格式:*
```bash
card_no=CARD123456789&package_id=100&strategy=1&access_key=ak_test123×tamp=1730619000&nonce=test123&signature=abc123def456
```
**支付说明**:
- **支付方式**: 当前仅支持余额支付
- **支付要求**: 账户余额必须充足，余额不足时订购失败
- **支付安全**: 无需提供支付密码，直接从账户余额扣除
- **支付流程**: 系统自动验证余额并扣费，无需额外操作
**生效策略说明**:
| 策略值 | 生效时间 | 描述 | 适用场景 |
|-----|------|---------------|----------|
| 1 | 本月生效 | 套餐立即生效，流量当月可用 | 立即需要使用流量 |
| 2 | 次月生效 | 套餐次月生效，流量下月可用 | 预订下月套餐 |
**请求示例**:
*使用 JSON 格式 (推荐):*
```bash
POST /api/v1/orders
Host: 接口地址
Content-Type: application/json
{
"card_no": "CARD123456789",
"package_id": 100,
"strategy": 1,
"access_key": "ak_test123",
"timestamp": "1730619000",
"nonce": "test123",
"signature": "abc123def456"
}
```
*使用 Form 格式:*
```bash
POST /api/v1/orders
Host: 接口地址
Content-Type: application/x-www-form-urlencoded
card_no=CARD123456789&package_id=100&strategy=1&access_key=ak_test123×tamp=1730619000&nonce=test123&signature=abc123def456
```
**响应信息**:
- **状态码**: `200 OK` / `400 Bad Request` / `403 Forbidden`
- **Content-Type**: `application/json`
**成功响应**:
```json
{
"code": "OK",
"msg": "ok",
"data": {
"order_no": "ORD202411030001"
},
"ok": true
}
```
**订购流程**:
1. 验证API权限和卡板状态
2. 检查账户余额是否充足
3. 验证套餐可用性和生效策略
4. 创建订单并从余额扣费
5. 应用套餐配置
6. 返回订单号
**业务规则**:
- 仅支持余额支付，需确保账户余额充足
- 余额不足时订购失败，返回错误信息
- 套餐生效时间取决于选择的策略参数
- 订购成功后不可撤销，请谨慎操作