第三方客户接入 API

接入约定

请勿把接口密钥放入 URL。管理员重新生成密钥后，旧密钥立即失效。

完整JSON加密规则

1. 将原始请求对象序列化为UTF-8 JSON字符串。
2. 使用16位AES密钥和 AES/ECB/PKCS5Padding 加密完整JSON字符串。
3. 将密文字节进行标准Base64编码。
4. 把Base64结果放入实际请求体的 data 字段。

加密前完整JSON

{"phone":"13800138000","name":"张先生","channel":"渠道A","note":"客户有意向"}

实际发送的请求体

{
  "data": "Base64编码的AES密文"
}

成功响应格式

{
  "code": 200,
  "msg": "操作成功",
  "data": "Base64编码的完整响应JSON密文"
}

响应时先Base64解码，再使用同一个AES密钥解密 data。解密结果是原始完整JSON。PKCS5Padding在AES实现中按16字节块进行兼容填充。

1. 单条添加

加密前完整JSON

{
  "phone": "13800138000",
  "name": "张先生",
  "channel": "渠道A",
  "note": "实时推送客户",
  "auto_assign": true
}

auto_assign 可不传，默认 true。系统按坐席创建顺序轮询分配，分到最后一名后回到第一名，并跳过停用或被管理员排除的坐席；传 false 时进入公海。管理员可在系统设置中勾选多个启用坐席，停用坐席为灰色且无法勾选。重复号码保持原分配关系，也不会推进轮询顺序。

解密响应data后的新增结果

{
  "success": true,
  "created": true,
  "duplicate": false,
  "contact_id": 123,
  "phone": "13800138000",
  "channel": "渠道A",
  "assignee_id": 5,
  "assignee_name": "坐席小李",
  "auto_assigned": true
}

解密响应data后的重复结果

{
  "success": true,
  "created": false,
  "duplicate": true,
  "contact_id": 123,
  "phone": "13800138000"
}

2. 批量添加

加密前完整JSON

{
  "contacts": [
    {"phone": "13800138000", "name": "张先生", "channel": "渠道A", "note": "客户有意向", "auto_assign": true},
    {"phone": "13900139000", "name": "李女士", "channel": "渠道A", "note": "稍后回访", "auto_assign": true}
  ]
}

批量新增会逐条按照同一个坐席顺序轮询分配，并与网页手动添加、表格导入共用轮询进度。每条客户都可单独设置 auto_assign。

解密响应data后的JSON

{
  "success": true,
  "total": 2,
  "created": 1,
  "duplicate": 1,
  "invalid": 0,
  "items": [
    {"index": 0, "created": true, "duplicate": false, "contact_id": 124, "phone": "13800138000", "assignee_id": 5, "assignee_name": "坐席小李", "auto_assigned": true},
    {"index": 1, "created": false, "duplicate": true, "contact_id": 120, "phone": "13900139000", "assignee_id": 8, "assignee_name": "坐席小王", "auto_assigned": false}
  ]
}

3. 手机号前8位撞库

提交手机号前8位，系统查询相同前缀的现有客户，并返回这些完整手机号对应的32位小写MD5。该接口只查询数据，不创建客户。

单个前缀加密前完整JSON

{
  "prefix": "18645556"
}

实际发送的请求体

{
  "data": "将上面完整JSON使用16位AES密钥加密后的Base64字符串"
}

cURL请求模板

curl -X POST "接口地址" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR8KEY" \
  -d '{"data":"BASE64_AES_CIPHERTEXT"}'

请勿直接发送 {"prefix":"18645556"}。需要先加密这段完整JSON，再将Base64密文放进外层 data 字段。密文会随着AES密钥和原始JSON内容变化。

多个前缀加密前完整JSON（最多100个）

{
  "prefixes": ["18645556", "13800138"]
}

解密响应data后：匹配到手机号

{
  "msg": "操作成功",
  "code": 200,
  "data": [
    "551bfd65d914a082d4c05cfcd97cf2a3",
    "661bfd65d914a082d4c05cfc887cf2a3"
  ]
}

解密响应data后：未匹配到手机号

{
  "msg": "操作成功",
  "code": 200,
  "data": []
}

MD5计算规则：手机号转为纯数字；中国大陆号码带 +86 或 86 时先去掉国家码；使用完整手机号计算无盐MD5，并输出32位小写十六进制字符串。

4. 查询客户管理

查询客户管理中的客户姓名、手机号、星级和备注。支持单个手机号、多个手机号、关键字以及分页筛选。

加密前完整JSON参数

按单个手机号查询

{"phone":"13800138000","page":1,"page_size":100}

按多个手机号查询

{"phones":["13800138000","13900139000"]}

解密响应data后的JSON

{
  "success": true,
  "total": 1,
  "page": 1,
  "page_size": 100,
  "pages": 1,
  "items": [
    {
      "name": "张先生",
      "phone": "13800138000",
      "rating": 5,
      "note": "客户有意向，明天下午回访"
    }
  ]
}

所有筛选参数都不传时，接口会按客户编号倒序分页返回全部客户。请求和响应仍需使用同一套完整JSON AES加密规则。

5. 查询通话记录和客户星级

查询通话记录人、客户、通话状态及该客户当前的0至5星评分。客户星级由所属坐席或管理员在客户管理中填写，支持分页以及按坐席、星级筛选。

加密前完整JSON

请求示例

{"page":1,"page_size":100,"rating":5}

解密响应data后的JSON

{
  "success": true,
  "total": 1,
  "page": 1,
  "page_size": 100,
  "pages": 1,
  "items": [
    {
      "task_id": 18,
      "contact_id": 31,
      "user_id": 5,
      "user_name": "坐席小李",
      "customer_name": "张先生",
      "phone": "13800138000",
      "channel": "渠道A",
      "status": "completed",
      "call_result": "talked",
      "record_text": "客户有意向",
      "rating": 5,
      "created_at": "2026-09-16T08:00:00+00:00",
      "connected_at": "2026-09-16T08:00:05+00:00",
      "ended_at": "2026-09-16T08:02:00+00:00"
    }
  ]
}

字段说明

新客户默认按坐席顺序自动分配。手机号全局唯一；合作方可安全重试，重复号码会返回原客户编号且不会改变原分配关系或轮询进度。

cURL 示例