客户管理 API

概述

客户管理 API 用于管理客户档案、标签体系和画像数据。通过这些接口可以构建客户 360° 视图，支持个性化服务和精准营销。

创建客户档案

新建客户档案，通常在首次对话时自动创建，也可通过 API 手动创建。

POST /api/kf/customer
Content-Type: application/json
Authorization: Bearer {access_token}
X-Tenant-Id: {tenant_id}

{
  "name": "张三",
  "phone": "13800138000",
  "email": "zhangsan@example.com",
  "source": "web_widget",
  "tags": ["VIP", "企业客户"],
  "custom_fields": {
    "company": "某某科技有限公司",
    "industry": "互联网"
  }
}

成功响应：

{
  "code": 0,
  "message": "客户创建成功",
  "data": {
    "id": "cus_9k2m4n7p",
    "name": "张三",
    "phone": "13800138000",
    "email": "zhangsan@example.com",
    "source": "web_widget",
    "tags": ["VIP", "企业客户"],
    "created_at": "2025-01-15T14:20:00+08:00",
    "last_active": "2025-01-15T14:20:00+08:00"
  }
}

查询客户列表

GET /api/kf/customer/list?tag=VIP&page=1&page_size=20
Authorization: Bearer {access_token}
X-Tenant-Id: {tenant_id}

查询参数：

• tag（可选）：按标签筛选
• source（可选）：按来源筛选（web_widget / wechat / email / api）
• keyword（可选）：搜索客户姓名、手机号、邮箱
• page / page_size：分页参数

获取客户详情

GET /api/kf/customer/{customer_id}
Authorization: Bearer {access_token}
X-Tenant-Id: {tenant_id}

返回客户完整档案，包含基本信息、标签、历史对话摘要和自定义字段。

更新客户标签

PATCH /api/kf/customer/{customer_id}/tags
Content-Type: application/json
Authorization: Bearer {access_token}
X-Tenant-Id: {tenant_id}

{
  "add_tags": ["高价值", "复购客户"],
  "remove_tags": ["新客"]
}

💡 建议：建立统一的标签命名规范，避免重复标签。推荐使用「分类:标签名」格式，例如「等级:VIP」「来源:微信」。

更新客户档案

PUT /api/kf/customer/{customer_id}
Content-Type: application/json
Authorization: Bearer {access_token}
X-Tenant-Id: {tenant_id}

{
  "name": "张三（已核实）",
  "custom_fields": {
    "company": "某某科技集团有限公司"
  }
}

客户画像数据

获取客户的画像分析数据，包括活跃度、偏好渠道、常见咨询主题等。

GET /api/kf/customer/{customer_id}/profile
Authorization: Bearer {access_token}
X-Tenant-Id: {tenant_id}

// 响应示例
{
  "code": 0,
  "data": {
    "customer_id": "cus_9k2m4n7p",
    "total_conversations": 47,
    "first_seen": "2024-11-20T09:00:00+08:00",
    "last_active": "2025-01-15T14:20:00+08:00",
    "preferred_channel": "web_widget",
    "top_topics": ["订单查询", "售后服务", "产品咨询"],
    "satisfaction_avg": 4.6,
    "lifetime_value": 12500
  }
}