mipu-open/docs/09-02_device-bind.md

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

请求体参数

{
  "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

返回参数

成功时返回任务信息：

{
  "success": true,
  "message": "VCC卡绑定任务已提交",
  "taskId": "task-bind-123456"
}

参数名称	类型	说明
success	Boolean	是否成功提交
message	String	结果消息
taskId	String	任务ID，用于查询任务状态

失败时返回：

{
  "success": false,
  "message": "设备离线，无法执行绑定任务",
  "taskId": null
}

业务案例

绑定VCC卡

请求

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"
    }
  }'

响应

{
  "success": true,
  "message": "VCC卡绑定任务已提交",
  "taskId": "task-bind-123456"
}

查询绑定任务进度

使用返回的taskId查询任务状态：

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 字段是否已更新为新卡号。