开放平台：客服账号同步

客服同步用于维护指定商户下的客服账号，不创建商户。调用前必须先完成商户账号同步。

调用前请先完成开放平台鉴权，取得密钥并按统一 HMAC 规则签名。

本接口依赖已存在的商户；完整流程是先执行商户账号同步，再同步客服账号。

同步客服

POST /open/agent/sync

请求参数

字段	必填	说明
agent_id	否	第三方客服 ID。首次传入时会作为本地客服 ID 保存；不传则由系统生成 op 前缀 ID。后续建议始终传同一 ID。
bid	是	客服所属商户 ID，商户必须已存在。
account_state	是	客服状态：normal 为启用，forbidden 为禁用。每次同步都会更新该状态。
username	新建时是	客服登录名；字母、数字、下划线或连字符，长度 1–60，且全系统唯一。已有客服传入时会更新。
nickname	新建时是	客服昵称，最长 128 个字符。已有客服传入时会更新。
avatar	否	客服头像的长期有效 HTTPS URL，最长 2048 个字符。传入时更新；首次不传使用系统默认头像。
password	新建时是	客服登录密码，长度 6–128。服务端只保存密码哈希；已有客服不传则保持原密码，传入则更新。

接口优先按 agent_id 查找客服；未传 agent_id 时按 username 查找。若两者同时传入但指向不同客服，返回 AGENT_ID_CONFLICT。新建客服默认角色为普通客服（normal）、默认离线，过期时间继承所属商户。

{
  "agent_id": "merchant_10001_agent_01",
  "bid": "merchant_10001",
  "account_state": "normal",
  "username": "merchant_10001_agent_01",
  "nickname": "客服一",
  "avatar": "https://cdn.example.com/avatar/agent_01.webp",
  "password": "ChangeMe_2026"
}

成功响应：

{
  "code": 0,
  "msg": "ok",
  "data": {
    "agent_id": "merchant_10001_agent_01",
    "bid": "merchant_10001",
    "account_state": "normal",
    "created": true
  }
}

客服同步不会改变商户状态；停用单个客服仅更新该客服的 account_state。

查询客服

POST /open/agent/query

请求体仅包含 agent_id：

{
  "agent_id": "merchant_10001_agent_01"
}

客服存在时：

{
  "code": 0,
  "msg": "ok",
  "data": {
    "agent_id": "merchant_10001_agent_01",
    "exists": true,
    "bid": "merchant_10001",
    "username": "merchant_10001_agent_01",
    "nickname": "客服一",
    "avatar": "https://cdn.example.com/avatar/agent_01.webp",
    "account_state": "normal"
  }
}

客服不存在时：

{
  "code": 0,
  "msg": "ok",
  "data": {
    "agent_id": "merchant_10001_agent_01",
    "exists": false
  }
}

查询结果永不返回密码或密码哈希。

常见错误

通用鉴权错误见开放平台鉴权。

错误码	HTTP 状态	处理建议
ACCOUNT_SYNC_DISABLED	403	在总后台开启“商户账号同步”。
BUSINESS_NOT_FOUND	404	先调用商户同步接口创建对应 bid。
USERNAME_EXISTS	409	修改为未被其他商户客服占用的用户名。
AGENT_ID_EXISTS	409	使用未被其他客服或商户占用的 agent_id。
AGENT_ID_CONFLICT	409	确保 agent_id 与 username 指向同一客服。
AGENT_REQUIRED	422	新建客服时补充 username、nickname、password。
AGENT_ID_INVALID	422	使用 1–64 位的字母、数字、下划线或连字符作为客服 ID。
AVATAR_INVALID	422	使用最长 2048 字符的 HTTPS 头像地址。