b450b512a2
- 添加 mipu-api 作为 git submodule (Claude Code Skill) - 迁移 API 文档源文件到 docs/ 目录统一维护 - 添加 Gitea Actions 工作流：tag推送自动打包docs并发布Release - Skill 运行时自动从 mipu-open Release 下载最新文档 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
144 lines
3.4 KiB
Markdown
144 lines
3.4 KiB
Markdown
<!-- mipuyun-api-doc: device-bind -->
|
||
# device/bind - VCC卡绑定
|
||
|
||
## 概述
|
||
|
||
VCC卡绑定API用于向设备提交VCC卡绑定请求。绑定过程是异步的，提交后会返回任务ID，可以通过任务查询接口查询绑定进度。
|
||
|
||
### 用户使用场景
|
||
|
||
本接口用于：
|
||
- 为在线设备绑定新的VCC卡
|
||
- 替换设备当前绑定的VCC卡
|
||
|
||
## 请求说明
|
||
|
||
| 项目 | 值 |
|
||
|------|-----|
|
||
| **请求地址** | `https://${endpoint}/device/bind` |
|
||
| **请求方法** | POST |
|
||
| **注意事项** | 绑定过程是异步的，需要轮询任务状态 |
|
||
|
||
### Header 参数
|
||
|
||
| 参数名称 | 类型 | 是否必选 | 示例值 | 说明 |
|
||
|----------|------|----------|--------|------|
|
||
| Content-Type | String | 是 | application/json | 固定值，指定请求体格式为 JSON |
|
||
| client-key | String | 是 | xxxxx | 联系我们获取生产环境 key |
|
||
| client-secret | String | 是 | xxxxx | 联系我们获取生产环境 secret |
|
||
|
||
### 请求体参数
|
||
|
||
```json
|
||
{
|
||
"deviceId": "device-001",
|
||
"creditCard": {
|
||
"cardNumber": "4242424242424242",
|
||
"cvv": "123",
|
||
"expiryDate": "12/25"
|
||
}
|
||
}
|
||
```
|
||
|
||
| 参数名称 | 类型 | 是否必选 | 示例值 | 说明 |
|
||
|----------|------|----------|--------|------|
|
||
| deviceId | String | 是 | "device-001" | 设备编号 |
|
||
| creditCard | Object | 是 | - | 信用卡信息 |
|
||
| creditCard.cardNumber | String | 是 | "4242424242424242" | 卡号 |
|
||
| creditCard.cvv | String | 是 | "123" | CVV码 |
|
||
| creditCard.expiryDate | String | 是 | "12/25" | 有效期，格式：MM/YY |
|
||
|
||
## 返回参数
|
||
|
||
成功时返回任务信息：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "VCC卡绑定任务已提交",
|
||
"taskId": "task-bind-123456"
|
||
}
|
||
```
|
||
|
||
| 参数名称 | 类型 | 说明 |
|
||
|----------|------|------|
|
||
| success | Boolean | 是否成功提交 |
|
||
| message | String | 结果消息 |
|
||
| taskId | String | 任务ID，用于查询任务状态 |
|
||
|
||
失败时返回：
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "设备离线，无法执行绑定任务",
|
||
"taskId": null
|
||
}
|
||
```
|
||
|
||
## 业务案例
|
||
|
||
### 绑定VCC卡
|
||
|
||
### 请求
|
||
|
||
```bash
|
||
curl -X POST "https://${endpoint}/device/bind" \
|
||
-H "Content-Type: application/json" \
|
||
-H "client-key: your_key" \
|
||
-H "client-secret: your_secret" \
|
||
-d '{
|
||
"deviceId": "device-001",
|
||
"creditCard": {
|
||
"cardNumber": "4242424242424242",
|
||
"cvv": "123",
|
||
"expiryDate": "12/25"
|
||
}
|
||
}'
|
||
```
|
||
|
||
### 响应
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "VCC卡绑定任务已提交",
|
||
"taskId": "task-bind-123456"
|
||
}
|
||
```
|
||
|
||
### 查询绑定任务进度
|
||
|
||
使用返回的taskId查询任务状态：
|
||
|
||
```bash
|
||
curl -X GET "https://${endpoint}/device/task/task-bind-123456" \
|
||
-H "client-key: your_key" \
|
||
-H "client-secret: your_secret"
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### 绑定是同步还是异步的？
|
||
|
||
绑定是**异步操作**。提交绑定请求后会立即返回任务ID，需要通过任务查询接口轮询任务状态。
|
||
|
||
### 绑定失败的可能原因？
|
||
|
||
- 设备离线（status=OFFLINE）
|
||
- 设备正在执行其他任务（taskStatus=PROCESSING）
|
||
- 信用卡信息格式错误
|
||
- 信用卡已过期
|
||
|
||
### 如何判断绑定是否完成？
|
||
|
||
通过任务查询接口检查任务状态：
|
||
- **PENDING**：任务在队列中等待
|
||
- **PROCESSING**：正在绑定中
|
||
- **COMPLETED**：绑定完成
|
||
- **FAILED**：绑定失败
|
||
|
||
### 绑定完成后如何验证？
|
||
|
||
再次调用设备列表接口，查看设备的 `vccCardNumber` 字段是否已更新为新卡号。
|