mipu-open/docs/09-03_device-unbind.md

device/unbind - VCC卡解绑

概述

VCC卡解绑API用于向设备提交VCC卡解绑请求。解绑过程是异步的，提交后会返回任务ID，可以通过任务查询接口查询解绑进度。

用户使用场景

本接口用于：

• 移除设备当前绑定的VCC卡
• 更换VCC卡前先解绑旧卡

请求说明

项目	值
请求地址	https://${endpoint}/device/unbind
请求方法	POST
注意事项	解绑过程是异步的，需要轮询任务状态

Header 参数

参数名称	类型	是否必选	示例值	说明
Content-Type	String	是	application/json	固定值，指定请求体格式为 JSON
client-key	String	是	xxxxx	联系我们获取生产环境 key
client-secret	String	是	xxxxx	联系我们获取生产环境 secret

请求体参数

{
  "deviceId": "device-001"
}

参数名称	类型	是否必选	示例值	说明
deviceId	String	是	"device-001"	设备编号

返回参数

成功时返回任务信息：

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

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

失败时返回：

{
  "success": false,
  "message": "设备没有绑定的VCC卡",
  "taskId": null
}

业务案例

解绑VCC卡

请求

curl -X POST "https://${endpoint}/device/unbind" \
  -H "Content-Type: application/json" \
  -H "client-key: your_key" \
  -H "client-secret: your_secret" \
  -d '{
    "deviceId": "device-001"
  }'

响应

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

查询解绑任务进度

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

curl -X GET "https://${endpoint}/device/task/task-unbind-123456" \
  -H "client-key: your_key" \
  -H "client-secret: your_secret"

常见问题

解绑是同步还是异步的？

解绑是异步操作。提交解绑请求后会立即返回任务ID，需要通过任务查询接口轮询任务状态。

解绑失败的可能原因？

• 设备离线（status=OFFLINE）
• 设备正在执行其他任务（taskStatus=PROCESSING）
• 设备没有绑定的VCC卡（vccCardNumber为空）

如何判断解绑是否完成？

通过任务查询接口检查任务状态：

• PENDING：任务在队列中等待
• PROCESSING：正在解绑中
• COMPLETED：解绑完成
• FAILED：解绑失败

解绑完成后如何验证？

再次调用设备列表接口，查看设备的 vccCardNumber 字段是否已为空。