浅念
129 lines
4.5 KiB
Markdown
129 lines
4.5 KiB
Markdown
# 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. 请求体
|
||
|
||
```json
|
||
{
|
||
"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"|"ai", text, at}`，at 同正 8 区规则 |
|
||
| `summary` | 一句话摘要，≤200 字 |
|
||
| `attachments` | 附件数组 `{filename, content_b64}`；单文件 ≤5MB、单条 ≤5 个 |
|
||
|
||
## 3. 响应
|
||
|
||
**HTTP 200——单条数据有问题不会挂掉整包**，逐条返回结果：
|
||
|
||
```json
|
||
{
|
||
"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 后端侧。*
|