服务端 API 接口文档
文档中心/LG 开放平台/绑定设备到渠道
绑定设备到渠道
更新时间：2026/08/18

将硬件设备 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

请求头参数

Header必填说明
Authorization是Bearer {API Key}，接口鉴权，所有请求均需携带
Content-Type否仅 POST/PUT 携带 JSON 请求体时需要，值为 application/json

请求路径参数

参数类型必填说明
channel_idinteger是硬件渠道 ID（从 publishings[].hardware_channels 或渠道列表取得）

请求体参数

字段类型必填说明
device_idstring是设备 ID，该设备必须已存在于指定渠道下
product_keystring否产品型号 ID；渠道内存在重复设备 ID 时必须提供
external_user_idstring是外部用户 ID，同一渠道下必须唯一
external_user_nicknamestring否外部用户昵称

请求示例

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_idstring设备 ID
product_keystring产品型号 ID
channel_idinteger渠道 ID
binding_idinteger绑定记录 ID
character_idinteger设备绑定的角色实例 ID
external_user_idstring外部用户 ID
external_user_nicknamestring外部用户昵称

⚠️错误码

错误码

校验项error_codeHTTP说明
渠道不存在CHANNEL_NOT_FOUND404指定 channel_id 不存在
渠道非硬件类型CHANNEL_NOT_HARDWARE400渠道类型不是官方/商家硬件
渠道未上架CHANNEL_OFFLINE400渠道状态为下架
令牌无权限CHANNEL_NOT_AUTHORIZED403API Key 未关联该渠道所属上架
设备不存在DEVICE_NOT_FOUND404device_id 在该渠道下不存在
设备 ID 不唯一DEVICE_ID_AMBIGUOUS409渠道内多个同 ID 设备，需补 product_key
角色未绑定DEVICE_CHARACTER_NOT_BOUND409设备在该渠道下没有有效角色绑定
外部用户 ID 重复EXTERNAL_USER_ID_DUPLICATE409同一渠道下已有其他设备绑定该 external_user_id
必填参数缺失—400device_id 或 external_user_id 为空
← 上一个GET /api/open/publishings/{id} 下一个 →DELETE /api/open/channels/{channel_id}/bind-device