Appearance
获取客户列表
| 拥有此API的权限集 |
|---|
| SCRM-客户管理 |
请求方式及url
- 请求方式：
POST - 请求头：
Content-Type:application/json - 接口地址：
https://api.xiaoe-tech.com/xe.scrm.customers.list/1.0.0 - 频率限制：
1s/1次
接口调试
请求参数
响应结果
暂无响应数据
请求参数
| 参数名 | 必选 | 类型 | 说明 | 备注 |
|---|---|---|---|---|
| access_token | 是 | string | 专属token | 沿用公共认证规范 |
| corp_id | 是 | string | 企业 ID | 必须为当前店铺绑定的有效企业 |
| page | 否 | int | 页码 | 默认 1，从 1 开始 |
| page_size | 否 | int | 每页数量 | 默认 20，最大 100 |
| display_fields | 否 | array<string> | 需要补充名称的展示字段 | 不传或传 [] 时不追加展示字段；允许范围见下表 |
| filters | 否 | object | 客户筛选条件 | 不传或传 {} 时使用默认查询条件 |
展示字段 display_fields
原字段的值和类型保持不变，选中的字段额外返回 <字段名>_display。只允许以下 7 项，超出范围返回参数错误。
| 可选值 | 补充信息 | 追加字段类型 |
|---|---|---|
| follow_user_id | 企微员工名称 | object：{id, name} |
| corp_tag_list | 企业标签名称 | array<object>：[{id, name}] |
| follow_user_channel_id | 添加渠道名称 | object：{id, name} |
| add_way | 添加方式名称 | object：{id, name} |
| obtain_channel | 获客渠道名称 | array<object>：[{id, name}] |
| active_channel | 活跃渠道名称 | array<object>：[{id, name}] |
| project | 项目名称 | array<object>：[{id, name}] |
展示结构的 id、name 均为字符串。一般情况下，名称未查到时使用 ID 兜底；添加渠道中的一客一码规则名称未查到时使用“分配规则”。
筛选条件 filters
| 参数名 | 类型 | 说明 |
|---|---|---|
| external_user_ids | array<string> | 企微客户 ID 列表 |
| search_type | string | 搜索类型，允许值见下文 |
| keyword | string | 单个搜索关键词 |
| batch_keywords | array<string> | 批量搜索关键词；去除首尾空白、空项和重复项 |
| follow_user_ids | array<string> | 跟进员工的企微 ID 列表，不是小鹅平台用户 ID；不传或空数组时不按员工筛选 |
| corp_tags | object | 企业标签匹配，结构见下文 |
| exclude_corp_tag_ids | array<string> | 排除企业标签 ID 列表，可与 corp_tags 同时使用 |
| source | object | 添加方式和渠道筛选，结构见下文 |
| status | object | 流失状态，结构见下文 |
| time_range | object | 添加、流失时间范围，结构见下文 |
| project_ids | array<string> | 项目 ID 列表 |
| duplicate_only | bool | 是否仅查重复客户，默认 false |
关键词搜索
search_type 支持以下四种类型：
| 值 | 含义 |
|---|---|
| customer_name | 客户名称 |
| follow_user_remark | 员工对客户的备注 |
| follow_user_description | 员工对客户的描述 |
| xiaoe_user_id | 小鹅用户 ID |
传入 keyword 或有效的 batch_keywords 时，必须指定 search_type。客户名称、备注、描述搜索忽略字母大小写：单关键词为模糊匹配，批量关键词为精确匹配。按小鹅用户 ID 搜索时应传入对应关键词；没有关键词时返回空列表。
json
{
"search_type": "xiaoe_user_id",
"batch_keywords": ["u_example_1", "u_example_2"]
}标签筛选
| 对象 | 子字段 | 类型 | 说明 |
|---|---|---|---|
| corp_tags | mode | string | any：命中任一标签；all：命中全部；none：无标签 |
| corp_tags | tag_ids | array<string> | 企业标签 ID 列表 |
企业标签按 ID 筛选，排除企业标签使用 exclude_corp_tag_ids，可与 corp_tags 同时生效。
json
{
"corp_tags": {"mode": "any", "tag_ids": ["tag_1"]},
"exclude_corp_tag_ids": ["tag_2"]
}来源筛选 source
| 子字段 | 类型 | 说明 |
|---|---|---|
| add_ways | array<string> | 添加方式编码，例如 "1" 扫描二维码、"3" 名片分享 |
| channels | array<string> | 添加渠道 ID，例如渠道活码 10001；接口会自动拼接 s_ 前缀 |
| channel_remark | string | 渠道备注，模糊匹配 |
| obtain_channels | array<string> | 获客渠道 ID 列表 |
| active_channels | array<string> | 活跃渠道 ID 列表 |
状态筛选 status
| 子字段 | 类型 | 说明 |
|---|---|---|
| customer_churn_states | array<string> | 流失状态："-1" 全部、"0" 未流失、"1" 已流失；兼容整数数组 |
时间筛选 time_range
| 子字段 | 类型 | 说明 |
|---|---|---|
| add_start | string | 添加时间起点 |
| add_end | string | 添加时间终点 |
| churn_start | string | 流失时间起点 |
| churn_end | string | 流失时间终点 |
时间支持 YYYY-MM-DD、YYYY-MM-DD HH:mm:ss 或 RFC3339，例如 2026-09-01 00:00:00。起点不能晚于终点。
请求示例
以下示例展示全部可用筛选字段，实际调用按需组合；单个搜索使用 keyword，批量搜索使用 batch_keywords，选择其中一种即可。示例中的客户、员工、标签和渠道 ID 请替换为实际值。
json
{
"access_token": "xe_xxxxx",
"corp_id": "corp_xxx",
"page": 1,
"page_size": 20,
"display_fields": [
"follow_user_id",
"corp_tag_list",
"add_way",
"obtain_channel"
],
"filters": {
"external_user_ids": [
"external_1"
],
"search_type": "customer_name",
"keyword": "客户示例",
"batch_keywords": [
"客户示例"
],
"follow_user_ids": [
"staff_1"
],
"corp_tags": {
"mode": "any",
"tag_ids": [
"tag_1"
]
},
"exclude_corp_tag_ids": [
"tag_2"
],
"source": {
"add_ways": [
"1"
],
"channels": [
"10001"
],
"channel_remark": "活动报名",
"obtain_channels": [
"11"
],
"active_channels": [
"12"
]
},
"status": {
"customer_churn_states": [
"1"
]
},
"time_range": {
"add_start": "2026-09-01 00:00:00",
"add_end": "2026-09-17 23:59:59",
"churn_start": "2026-09-01 00:00:00",
"churn_end": "2026-09-17 23:59:59"
},
"project_ids": [
"21"
],
"duplicate_only": false
}
}返回参数
| 参数名 | 类型 | 说明 |
|---|---|---|
| code | int | 状态码，0 表示成功，非 0 表示失败 |
| msg | string | 状态信息 |
| data | object | 返回数据 |
| data.list | array<object> | 客户跟进关系列表，无数据时为 [] |
| data.page | int | 当前页码 |
| data.page_size | int | 每页数量 |
data.list 每条记录固定包含以下 18 个字段；customer_type、customer_churn_state、add_way 有效值返回整数，缺失或无法转换为整数时返回 null，列表仍正常返回；其他标量在关联数据缺失时可能返回空字符串，标签数组返回 []。头像为空时返回默认头像地址。
| 字段 | 类型 | 说明 |
|---|---|---|
| external_user_id | string | 企微客户 ID |
| name | string | 客户名称 |
| avatar | string | 头像地址 |
| customer_type | int / null | 客户类型 |
| xiaoe_user_id | string | 小鹅平台用户 ID |
| follow_user_id | string | 企微跟进员工 ID |
| follow_user_remark | string | 员工对客户的备注 |
| follow_user_description | string | 员工对客户的描述 |
| follow_user_createtime | string | 员工添加客户时间 |
| customer_churn_state | int / null | 流失状态：0 未流失、1 已流失 |
| customer_churn_time | string | 流失时间 |
| corp_tag_list | array<string> | 企业标签 ID 列表 |
| follow_user_channel_id | string | 添加渠道 ID |
| add_way | int / null | 添加方式编码 |
| channel_remark | string | 渠道备注 |
| obtain_channel | string | 获客渠道 ID，多个值时可能为逗号分隔字符串 |
| active_channel | string | 活跃渠道 ID，多个值时可能为逗号分隔字符串 |
| project | string | 项目 ID，多个值时可能为逗号分隔字符串 |
根据 display_fields 额外追加对应的 _display 字段，详见展示字段表。
返回示例
json
{
"code": 0,
"msg": "ok",
"data": {
"list": [
{
"external_user_id": "external_1",
"name": "客户示例",
"avatar": "https://example.com/avatar.png",
"customer_type": 1,
"xiaoe_user_id": "u_example_1",
"follow_user_id": "staff_1",
"follow_user_remark": "客户备注",
"follow_user_description": "客户描述",
"follow_user_createtime": "2026-09-10 10:00:00",
"customer_churn_state": 0,
"customer_churn_time": "",
"corp_tag_list": ["tag_1"],
"follow_user_channel_id": "s_10001",
"add_way": 1,
"channel_remark": "活动报名",
"obtain_channel": "11",
"active_channel": "",
"project": "21",
"follow_user_id_display": {"id": "staff_1", "name": "张三"},
"corp_tag_list_display": [{"id": "tag_1", "name": "重点客户"}],
"add_way_display": {"id": "1", "name": "扫描二维码"},
"obtain_channel_display": [{"id": "11", "name": "活动获客"}]
}
],
"page": 1,
"page_size": 20
}
}错误说明
公共认证错误沿用平台公共规范。业务请求失败时返回非 0 的 code，msg 描述失败原因。
| 情况 | 处理方式 |
|---|---|
| 分页参数无效 | page 从 1 开始，page_size 不超过 100 |
| display_fields 超出允许范围 | 只传展示字段表中的 7 项 |
| 企业标签筛选模式无效 | 使用 any、all 或 none |
| 流失状态无效 | 使用状态筛选表中的取值 |
| 时间格式错误或起点晚于终点 | 修正时间格式和范围 |
| 查询失败 | 根据 msg 排查，必要时联系技术支持 |