ai-kefu-jc/docs/AI_INQUIRY_PUSH_API.md

AI 客服询盘推送接口 · 对接文档（v1）

本文档交给 AI 客服项目侧实现。约定：AI 客服系统将询盘主动推送到本系统（UniService），本系统负责归档与后续导入。 对接开通时我方提供：生产域名 + X-Api-Key 密钥。文档版本 v1（2026-09-28）。

---

1. 接口定义

项	值
端点	POST /open/v1/inquiry/push
鉴权	请求头 X-Api-Key: <开通时分配>
格式	JSON，UTF-8
批量	单次 ≤ 50 条
幂等	按每条的 external_key——重复推送不会重复入库，请放心重试

2. 请求体

{
  "messages": [
    {
      "event": "new",
      "external_key": "ai-20260928-000123",
      "occurred_at": "2026-09-28T10:30:00+08:00",
      "contact": {
        "name": "Ivan",
        "phone": "+254722111117",
        "whatsapp": "+254722111117",
        "email": "ivan@example.com",
        "wechat": null,
        "skype": null
      },
      "intent_level": "high",
      "intent_reason": "客户主动询问库存与价格，三天内两次跟进",
      "profile": { "country": "肯尼亚", "source": "官网", "语言": "英语" },
      "conversation": [
        {"role": "customer", "text": "Do you have this car in stock?", "at": "2026-09-28T10:29:11+08:00"},
        {"role": "ai", "text": "Yes, could you leave your phone number?", "at": "2026-09-28T10:29:20+08:00"}
      ],
      "summary": "肯尼亚客户询库存车，已留手机号",
      "attachments": [
        {"filename": "chat.png", "content_b64": "<base64>"}
      ]
    }
  ]
}

字段说明

必填

字段	类型	说明
messages[].event	string	new=新询盘；update=更正（按 external_key 更新同一条询盘的内容）
messages[].external_key	string	贵系统内该询盘的唯一 id（幂等键）。同一 id 重复推送=计重复，不报错、不入库
messages[].occurred_at	string	询盘发生时间。一律正 8 区：2026-09-28T10:30:00+08:00 或北京时间字面值；不要发 UTC
messages[].contact	object	联系方式结构（见下）。phone / whatsapp / email 至少一个非空且有效，否则该条被拒

contact 结构（name/wechat/skype 可空）

字段	说明
name	客户称呼（可空）
phone	手机号，带国际区号（可空）
whatsapp	WhatsApp 号，带国际区号（可空）
email	邮箱（可空）
wechat / skype	可空

选填（强烈建议提供，原样归档不留丢失）

字段	说明
intent_level	意向等级：high / medium / low / unknown
intent_reason	意向评估理由原文
profile	客户画像，任意 JSON 对象，原样透传（贵系统什么结构就传什么）
conversation	完整对话记录数组，每条 `{role: "customer"
summary	一句话摘要，≤200 字
attachments	附件数组 {filename, content_b64}；单文件 ≤5MB、单条 ≤5 个

3. 响应

HTTP 200——单条数据有问题不会挂掉整包，逐条返回结果：

{
  "success": true,
  "data": {
    "accepted": 9,
    "duplicated": 1,
    "failed": [
      {"external_key": "ai-20260928-000131", "reason": "无有效联系方式(phone/whatsapp/email 至少一个)"}
    ]
  }
}

项	含义
accepted	新入库条数
duplicated	幂等键重复跳过条数（不是错误）
failed	被拒条目及原因（修正后可用同 external_key 重推，按新数据处理）

错误码

HTTP	场景	是否重试
401	密钥错误/缺失	否（检查密钥）
400	报文结构错误（JSON 解析失败、缺 messages 等）	否（修正报文）
5xx / 超时	我方侧异常	请重试（幂等保证安全）

4. 重试建议

• 5xx / 网络超时：指数退避重试，重试窗口 24 小时
• 单条 failed：修正数据后带同 external_key 重推

5. 对接流程

1. 我方提供：生产域名 + X-Api-Key
2. 贵方按本文档实现推送（建议先推 1-2 条真实样本联调）
3. 双方核对 accepted/duplicated/failed 与归档内容
4. 转正式定时推送（频率由贵方定，建议询盘产生后准实时或小时级批量）

---

本文档由 UniService 后端维护；接口问题反馈给 UniService 后端侧。