99客服开发文档

Appearance

开放平台：商户账号同步 ​

开放平台用于可信的第三方服务端将商户同步到 99 客服。一个第三方商户 ID 对应一个本地商户 bid；商户同步会创建或维护主客服。

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

商户同步完成后，如需继续维护该商户的客服账号，请使用客服账号同步。

同步商户与主客服 ​

http
POST /open/business/sync

请求参数 ​

字段必填说明
bid是第三方商户 ID，同时作为本地商户 ID。非空 UTF-8 字符串，最长 32 个字符。创建后不可修改。
agent_id否主客服 ID。可传第三方固定 ID；支持字母、数字、下划线或连字符，最长 64 个字符。首次不传时由系统生成，已关联主客服时必须与现有值一致。
account_state是商户状态：normal 为启用，forbidden 为停用。
username新建时是主客服登录名；字母、数字、下划线或连字符，长度 1–60，且全系统唯一。已存在商户传入时会更新。
nickname新建时是主客服昵称，最长 128 个字符。已存在商户传入时会更新。
avatar否主客服头像的长期有效 HTTPS URL，最长 2048 个字符。传入时更新；首次不传使用系统默认头像。
password新建时是主客服登录密码，长度 6–128。服务端只保存密码哈希；已有商户不传则保持原密码，传入则更新。

新建商户或已有商户尚未关联主客服时，必须提供 username、nickname 和 password。系统会创建一个 manager 级别、默认离线的主客服，并将内部 agent_id 写回商户。

已有商户可以只传 bid 与 account_state 进行停用或恢复，也可以同时传入用户名、昵称、头像、密码中的任意字段更新资料。若商户已存在但 agent_id 无效，系统会使用本次同步资料补建或关联主客服。

json
{
  "bid": "merchant_10001",
  "agent_id": "merchant_10001_main",
  "account_state": "normal",
  "username": "merchant_10001",
  "nickname": "示例商户",
  "avatar": "https://cdn.example.com/avatar/merchant_10001.webp",
  "password": "ChangeMe_2026"
}

成功响应：

json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "bid": "merchant_10001",
    "agent_id": "op01j7m8h9k2v3w4xz",
    "account_state": "normal",
    "created": true,
    "agent_created": true
  }
}
返回字段说明
agent_id主客服 ID；字符串，长度 1–64，仅允许字母、数字、下划线或连字符。第三方后端签发客服 Token 时使用。传入时原样保留；未指定时由开放平台生成 op 前缀 ID。
created本次是否创建了商户。
agent_created本次是否新建了主客服；关联已有同商户客服时为 false。

停用商户后，访客入口、客服登录、已有客服 Session 的后续工作台请求以及客服 Token 均会被拒绝；恢复商户后可重新登录或重新签发 Token。商户停用不会覆盖单个客服自身的禁用状态。

查询商户 ​

http
POST /open/business/query

请求体仅包含 bid：

json
{
  "bid": "merchant_10001"
}

商户存在时，返回商户状态及主客服公开资料：

json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "bid": "merchant_10001",
    "exists": true,
    "account_state": "normal",
    "main_agent": {
      "agent_id": "op01j7m8h9k2v3w4xz",
      "username": "merchant_10001",
      "nickname": "示例商户",
      "avatar": "https://cdn.example.com/avatar/merchant_10001.webp",
      "account_state": "normal"
    }
  }
}

商户不存在时：

json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "bid": "merchant_10001",
    "exists": false,
    "account_state": null,
    "main_agent": null
  }
}

查询结果永不返回密码或密码哈希。main_agent 为 null 表示商户未关联有效主客服，可使用完整的同步请求补建。

常见错误 ​

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

错误码HTTP 状态处理建议
BUSINESS_SYNC_DISABLED403在总后台开启“商户账号同步”。
USERNAME_EXISTS409修改为未被其他商户客服占用的用户名。
AGENT_ID_EXISTS409使用未被其他客服或商户占用的 agent_id。
AGENT_ID_CONFLICT409确保 agent_id 与 username 指向同一客服。
MAIN_AGENT_REQUIRED422新建或修复主客服时补充 username、nickname、password。
AGENT_ID_INVALID422使用 1–64 位的字母、数字、下划线或连字符作为客服 ID。
AVATAR_INVALID422使用最长 2048 字符的 HTTPS 头像地址。

Copyright © 99客服