# 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 后端侧。*