线索鸭 Webhook 推送接口文档

本文档用于说明如何通过 POST 请求，将线索数据推送到「线索鸭」系统中，完成线索的自动同步与管理。

一、接口基础信息

二、请求参数说明

请求体为 JSON 格式，所有字段均为可选字段，可根据业务场景按需传递，无需一次性传全。

三、请求示例

1. 完整请求示例（JSON）

{
    "name": "张三",
    "phone": "13800138000",
    "location_province": "广东省",
    "location_city": "广州市",
    "gender": "1",
    "external_lead_id": "BD-LEAD-20250506-0001",
    "clue_created_at": "2025-05-06 14:30:00",
    "wechat": "zhangsan_wx",
    "qq": "123456789",
    "email": "zhangsan@example.com",
    "ad_account_id": "1000001234",
    "ad_campaign_id": "CAMPAIGN_20250506_001",
    "ad_campaign_name": "广州疝气医院-春季推广",
    "ad_group_id": "GROUP_001",
    "ad_group_name": "广州地区-关键词定向",
    "ad_creative_id": "CREATIVE_001",
    "ad_keyword": "广州疝气手术多少钱",
    "landing_page_url": "https://xxx.com/landing/hernia001",
    "form_name": "在线预约表单",
    "remark": "客户咨询疝气微创手术，希望了解价格和预约时间"
}

2. 极简请求示例（仅核心字段）

{
    "phone": "13800138000",
    "name": "张三",
    "ad_keyword": "广州疝气治疗"
}

四、响应说明

请求成功/失败时，接口会返回固定格式的 JSON 响应，便于判断推送结果。

1. 成功响应（HTTP 状态码 200）

{"code":200,"msg":"线索接收成功","data":{"lead_id":"01KQY9YZFX2CRFSFVQ39YF9VT2"}}

五、字段映射与配置说明

推送前需在「线索鸭」后台完成字段映射配置，步骤如下：

1. 进入「线索鸭后台」-「接入分发」-「媒体账户」；

2. 添加账号授权，选择自有/第三方授权，输入授权名称

3.点击创建线索对接

4. 点击新建线索对接

5. 根据实际情况输入对接名称和选择相关的业务类型以及线索来源，点击下一步

6.字段映射无需填写，直接点击下一步

7. 根据需要填写数据过滤条件，点击完成并保存

8. 复制推送链接

六、常见问题与排查

1. 字段不生效/数据未同步：核对「字段名」是否完全一致（区分大小写，无多余转义符）；检查请求头是否为 Content-Type: application/json。
2. 线索重复推送：确保每个线索都携带唯一的 external_lead_id，系统会根据 phone + external_lead_id 自动去重
3. 推送失败：根据返回的msg进行修改