API REFERENCE
线索管理 API
管理翠鸟捕获的销售线索，支持 CRUD 操作、线索评分与 CRM 同步
线索数据结构
每条线索（Lead）对象包含访客身份信息、行为评分以及来源追踪数据，是翠鸟内容营销的核心数据实体。
{
"id": "lead_5xPqR8mNwK",
"email": "zhang.wei@example.com",
"name": "张伟",
"company": "北京某科技有限公司",
"job_title": "市场总监",
"phone": "+86 138 0000 0000",
"status": "qualified", // new | contacted | qualified | converted | lost
"score": 72, // 0-100，基于行为自动计算
"source_resource_id": "res_7fK2mPqLxNz",
"source_channel": "linkedin",
"utm": {
"source": "linkedin",
"medium": "social",
"campaign": "q1_whitepaper"
},
"behavior_summary": {
"total_page_views": 8,
"avg_dwell_seconds": 245,
"max_scroll_depth": 100,
"cta_clicks": 2
},
"custom_fields": {},
"created_at": "2024-03-15T09:12:33Z",
"updated_at": "2024-03-16T14:05:00Z",
"assigned_to": "user_sales_001"
}
创建 / 查询线索
列出线索
# 获取最近7天的线索，按评分降序
curl "https://api.cuiniao.com/v1/leads?days=7&sort=score&order=desc&limit=20" \
-H "Authorization: Bearer ck_live_xxxxxxxxxxxx"
手动创建线索
通常线索由访客提交表单自动创建，但也可通过 API 从外部系统导入线索。
curl -X POST https://api.cuiniao.com/v1/leads \
-H "Authorization: Bearer ck_live_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"email": "li.ming@company.com",
"name": "李明",
"company": "上海某贸易集团",
"job_title": "采购经理",
"source_channel": "offline_event",
"custom_fields": {
"event_name": "华南采购节2024"
}
}'
查询单条线索
curl "https://api.cuiniao.com/v1/leads/lead_5xPqR8mNwK" \
-H "Authorization: Bearer ck_live_xxxxxxxxxxxx"
翠鸟会基于访客行为数据自动计算线索评分（0-100），评分每小时更新一次。高评分线索建议优先跟进。
更新线索状态
销售流程推进时，通过 PATCH /v1/leads/{id} 更新线索状态和跟进信息。
curl -X PATCH https://api.cuiniao.com/v1/leads/lead_5xPqR8mNwK \
-H "Authorization: Bearer ck_live_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"status": "qualified",
"assigned_to": "user_sales_001",
"notes": "已电话沟通，有明确采购意向，预算约20万，Q2决策"
}'
可更新的字段包括：status、assigned_to、notes、custom_fields。线索评分由系统自动维护，不可手动覆盖。
与 CRM 同步
翠鸟支持将线索实时同步至主流 CRM 系统。通过控制台配置 CRM 集成后，新线索创建或状态变更时将自动推送至对应 CRM。
- 支持 Salesforce、HubSpot、纷享销客、销售易等主流 CRM
- 可通过
POST /v1/leads/{id}/sync-crm手动触发单条线索同步 - 批量同步：
POST /v1/leads/batch-sync-crm，支持最多 100 条/次
# 手动触发单条线索同步到已配置的 CRM
curl -X POST https://api.cuiniao.com/v1/leads/lead_5xPqR8mNwK/sync-crm \
-H "Authorization: Bearer ck_live_xxxxxxxxxxxx"
# 响应
{
"synced": true,
"crm_type": "salesforce",
"crm_record_id": "00Q5e000004XXXX",
"synced_at": "2024-03-16T14:10:00Z"
}