绑定设备到渠道
小程序对接引导
微信小程序请先通过 BLE 获取设备 device_id，再使用本页开放平台接口完成设备绑定；V2 的完整步骤见《V2 设备绑定、解绑与换绑》。
将硬件设备 ID 与外部用户 ID 关联，设备通过网关聊天时使用绑定用户身份。
注意
user_id 与 device_id 配合：绑定后，设备端产生的会话归属该用户（external_user_id），用户可通过 user_id（+ device_id 过滤）查询设备会话。解绑后该用户无法再查询对应硬件会话。
请求信息
请求 URI
POST https://lg.jimitu.top/api/open/channels/{channel_id}/bind-device请求头参数
| 请求头 | 必填 | 说明 |
|---|---|---|
Authorization | 是 | Bearer {API Key}，接口鉴权，所有请求均需携带 |
Content-Type | 否 | 仅 POST/PUT 携带 JSON 请求体时需要，值为 application/json |
请求路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| channel_id | integer | 是 | 硬件渠道 ID（从 publishings[].hardware_channels 或渠道列表取得） |
请求体参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| device_id | string | 是 | 设备 ID，该设备必须已存在于指定渠道下 |
| product_key | string | 否 | 产品型号 ID；渠道内存在重复设备 ID 时必须提供 |
| external_user_id | string | 是 | 外部用户 ID，同一渠道下必须唯一 |
| external_user_nickname | string | 否 | 外部用户昵称 |
请求示例
curl -X POST "https://lg.jimitu.top/api/open/channels/{channel_id}/bind-device" \
-H "Authorization: Bearer <your_api_key>" \
-H "Content-Type: application/json" \
-d '{
"device_id": "123456",
"product_key": "（可选，渠道内重复设备 ID 时必填）",
"external_user_id": "<user_id>",
"external_user_nickname": "（可选）用户昵称"
}'响应信息
响应体示例
{
"success": true,
"message": "External user bound to device successfully",
"data": {
"device_id": "123456",
"product_key": "...",
"channel_id": 100,
"binding_id": 999,
"character_id": 555,
"external_user_id": "<user_id>",
"external_user_nickname": "..."
}
}响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| device_id | string | 设备 ID |
| product_key | string | 产品型号 ID |
| channel_id | integer | 渠道 ID |
| binding_id | integer | 绑定记录 ID |
| character_id | integer | 设备绑定的角色实例 ID |
| external_user_id | string | 外部用户 ID |
| external_user_nickname | string | 外部用户昵称 |
错误码
错误码
| 校验项 | error_code | 状态码 | 说明 |
|---|---|---|---|
| 渠道不存在 | CHANNEL_NOT_FOUND | 404 | 指定 channel_id 不存在 |
| 渠道非硬件类型 | CHANNEL_NOT_HARDWARE | 400 | 渠道类型不是官方/商家硬件 |
| 渠道未上架 | CHANNEL_OFFLINE | 400 | 渠道状态为下架 |
| 令牌无权限 | CHANNEL_NOT_AUTHORIZED | 403 | API Key 未关联该渠道所属上架 |
| 设备不存在 | DEVICE_NOT_FOUND | 404 | device_id 在该渠道下不存在 |
| 设备 ID 不唯一 | DEVICE_ID_AMBIGUOUS | 409 | 渠道内多个同 ID 设备，需补 product_key |
| 角色未绑定 | DEVICE_CHARACTER_NOT_BOUND | 409 | 设备在该渠道下没有有效角色绑定 |
| 外部用户 ID 重复 | EXTERNAL_USER_ID_DUPLICATE | 409 | 同一渠道下已有其他设备绑定该 external_user_id |
| 必填参数缺失 | — | 400 | device_id 或 external_user_id 为空 |