配置 纷享销客 数据源
纷享销客数据源用于通过离线同步读取 CRM 对象中的数据,并写入平台预置仓。本文介绍纷享销客端的应用授权、数据源配置、同步方案创建和任务流挂载。
使用限制与准备事项
开始配置前,请确认以下限制和前置条件:
- 纷享销客仅支持作为数据来源,不支持作为数据去向,也不会回写纷享销客。
- 需由具备应用管理权限的企业管理员创建和维护自建应用,由 CRM 管理员配置访问员工的对象、字段和记录权限。
- 准备一个正常启用、可长期维护的员工账号作为访问身份,并明确账号负责人和权限维护人员。
- 确认需要同步的对象、字段和记录范围,以及平台运行环境能否访问企业所在云的纷享销客开放平台。
| 环境配置方式 | 适用场景 | 配置要求 |
|---|---|---|
| 不区分环境 | 开发环境与生产环境共用连接配置 | 准备一套应用凭据和 Employee ID,并确认访问权限符合要求 |
| 独立环境配置 | 开发环境与生产环境分别维护连接配置 | 分别准备可用凭据和 Employee ID,核对两个环境中的对象及字段权限,并分别完成连通性测试 |
在纷享销客中完成应用授权
创建并启用企业自建应用
- 使用企业管理员账号登录纷享销客网页版,进入管理后台。
- 打开 应用列表,选择 新建企业自建应用,填写应用名称、说明等信息并保存。
- 进入应用配置页面,启用开发者模式,按页面要求配置登录授权发起页域名和 IP 白名单。
- 确认应用在当前企业中处于启用状态,取得 App ID、App Secret 和 Permanent Code(永久授权码)。
IP 白名单应填写实际发起 API 请求的服务器出口公网 IP,由平台部署维护人员提供;存在多个出口时应完整登记。不要将浏览器所在电脑的 IP 作为服务器出口 IP 交付。
具体入口和配置说明参考纷享销客官方快速开始。
开通应用查询权限和员工数据权限
进入自建应用的 CRM 接口查询权限设置,按需要读取的对象范围开放以下查询权限。
| 权限用途 | 接口路径 |
|---|---|
| 查询对象列表 | /cgi/crm/v2/object/list |
| 查询对象描述及字段信息 | /cgi/crm/v2/object/describe |
| 查询预置对象数据 | /cgi/crm/v2/data/query |
| 查询自定义对象数据 | /cgi/crm/custom/v2/data/query |
应用接口权限和员工数据权限需要分别配置。CRM 管理员还应为访问员工检查以下内容:
| 权限层次 | 检查内容 |
|---|---|
| 对象权限 | 可以查看需要同步的业务对象 |
| 字段权限 | 可以读取需要同步的字段 |
| 记录范围 | 可以查看业务要求范围内的记录,包括对应部门、负责人或共享范围的数据 |
例如,需要读取某部门的客户记录时,员工的数据范围应覆盖该部门。仅能查看本人记录的员工,不能按已获得该部门全部记录权限来验收。详见官方数据权限说明。
获取 Employee ID 并核对开通结果
请管理员查询目标员工对应的 openUserId,作为数据源中的 Employee ID。可通过官方获取部门下成员简略信息等管理员流程核对人员,并记录返回的 openUserId;不要填写手机号、登录账号、工号或企业 ID。
由管理员确认企业所在云对应的 API 域名。默认值为 open.fxiaoke.com;其他云的域名可参考官方企业所在云域名说明,并确认当前平台接受该配置。官方云域名清单不代表当前平台已支持全部域名。
开通完成后,将 API 域名、App ID、App Secret、Permanent Code、Employee ID、已授权的数据范围、已登记的出口 IP 和维护负责人交付给平台配置人员。App Secret 和 Permanent Code 应通过企业认可的安全渠道交付,不要写入普通文档、日志或工单。
使用同一应用、同一 Employee ID 和实际服务器出口核对凭据、接口、对象、字段及记录范围。应用已启用或能够取得访问令牌,并不代表员工已获得所需的全部数据权限。
创建纷享销客数据源
- 进入 数据开发平台 > 集成 > 数据源,点击 + 数据源。
- 选择 纷享销客,点击 下一步,填写数据源名称和备注。
- 选择 不区分环境 或 独立环境配置。独立环境配置需要分别完成开发环境和生产环境的配置。
- 填写 API Domain、App ID、App Secret、Permanent Code 和 Employee ID。
- 在 连通性测试 中点击 测试。显示 可连通 后,点击 完成。
填写连接参数,并检查环境配置方式。
| 配置项 | 说明 |
|---|---|
| 数据源名称 | 当前空间内的数据源名称,需通过页面的名称及唯一性校验 |
| 备注 | 选填,用于说明用途或维护信息 |
| API Domain | 纷享销客开放平台的 API 域名,默认 open.fxiaoke.com;按企业所在云及平台支持情况配置 |
| App ID | 企业自建应用的应用 ID,必填 |
| App Secret | 上述应用对应的应用密钥,必填 |
| Permanent Code | 上述应用对应的永久授权码,必填 |
| Employee ID | 用于读取数据的员工 openUserId,必填;该员工需具有所需的数据权限 |
编辑已保存的数据源时,App Secret 和 Permanent Code 会以脱敏值显示;保留脱敏值即继续使用原凭据。需要更换时填写新值,并重新完成连通性测试。
连通性测试通过后,仍需在离线同步方案中确认目标对象、字段和记录范围。独立环境配置下,应分别核对开发环境与生产环境的访问权限。
创建离线同步方案
- 进入 数据开发平台 > 集成 > 离线同步,点击 + 集成方案。
- 在 数据来源 中选择 纷享销客及已创建的数据源。
- 选择 对象类型:预置对象或自定义对象。
- 在 来源对象 中按对象名称或 API 名搜索,选择需要同步的对象。
- 点击 数据预览,检查来源对象和可读取的数据内容是否符合预期。
选择对象类型和来源对象后,再预览数据。
切换对象类型后,原来选定的对象和字段映射会清空。请重新选择来源对象,并重新检查字段映射;来源对象未选定时,数据预览不可用。
字段映射与同步验证
支持的字段类型
| 字段类别 | 支持的纷享销客字段类型 |
|---|---|
| 文本与单值引用 | text、long_text、html_rich_text、phone_number、email、url、auto_number、select_one、master_detail、object_reference |
| 地区与位置 | country、province、city、district、location |
| 多值字段 | select_many、department、department_many、employee、employee_many、object_reference_many、tag、array |
| 数值 | number、currency、percentile |
| 布尔 | true_or_false |
| 日期与时间 | date、date_time、time |
| 计算与引用结果 | count、formula、quote,不包含图片、附件或签名结果 |
读取上述字段时,还需满足以下要求:
- 文本与单值引用、地区与位置字段的值应为字符串;多值字段应为字符串数组,数组中可以包含空值。
- 数值字段的小数位数须明确,且为 0~38。实际数值总精度不得超过 38 位,有效小数位须在字段声明的范围内。
- 布尔字段的值应为布尔值。日期和日期时间字段应提供整数毫秒时间戳,时间字段应提供整数值。
- 计算与引用字段读取已有结果;结果需为文本、数字、布尔值,或有效的数组、对象内容。其他字段类型请先通过数据预览和手动执行确认读取结果。
不支持的字段与限制
- 图片(
image)、附件(file_attachment)、签名(signature),以及返回这些内容的引用结果,例如quote(image),不支持读取。其他字段结果中包含附件或图片等媒体内容时,也不能作为普通字段内容同步。 - 缺少类型声明,或数值字段缺少有效小数位数声明时,字段不可用。页面中不支持读取的来源字段会置灰,请查看提示原因。
- 未启用的字段不参与读取。字段组(
group)本身不作为独立字段读取,其子字段可按各自类型选择。
配置与验证
完成数据来源配置后,在 数据去向 中选择或创建平台预置仓的目标表,并建立字段映射。
独立环境配置下,手动执行使用生产环境数据源配置。执行前请确认生产凭据、对象和字段权限,以及目标表均符合预期。
- 按业务需要设置目标表和写入方式。
- 在 字段映射 中,将需要读取的来源字段映射到目标字段。
- 不要将置灰字段作为可用字段配置,请根据提示调整需要同步的字段。
- 填写方案名称、负责人和备注后保存。
- 点击 手动执行,在执行记录中确认任务成功,再到目标表核对行数、字段和数据内容。
来源字段的名称用于识别业务含义,API 名用于区分对应字段。配置完成后,请逐项检查映射,避免将显示名称相近的字段错误关联。
以下为字段映射界面示例,请按实际业务核对字段对应关系。
| 现象 | 检查项 |
|---|---|
| 连通性测试失败 | 检查 API Domain、四项凭据及其对应关系,确认应用和员工账号未停用 |
| 提示 IP 未授权或访问被拒绝 | 请部署维护人员核对实际服务器出口 IP,并检查是否已完整登记到应用 IP 白名单 |
| 对象列表为空或找不到目标对象 | 检查对象类型是否正确,应用是否开放对象列表与查询权限,访问员工是否具有该对象权限 |
| 字段缺失或无法读取 | 检查应用的对象描述权限和员工的字段读取权限,并确认对象结构是否发生变化 |
| 预览或同步的记录少于预期 | 使用同一 Employee ID 核对员工的部门、负责人及共享范围,确认可读取的记录符合业务要求 |
| 来源字段置灰或无法读取 | 查看字段提示,检查字段类型及其实际内容是否在支持范围内 |
| 开发环境正常、生产任务失败 | 检查生产环境凭据、出口 IP、应用权限、员工数据范围,以及所选对象和字段是否可访问 |
挂载到任务流
手动验证成功后,可将离线同步方案挂载到任务流,按调度周期自动执行。
- 打开已保存的离线同步方案,点击 挂载到任务流。
- 选择目标任务流。
- 填写节点名,选择执行模式,并按需设置负责人和备注。节点类型和集成方案会自动带出。
- 点击 创建节点并挂载。挂载成功后,可点击 前往任务流检查节点位置和上下游依赖。
- 保存任务流并完成发布;生产调度将使用生产环境的数据源配置。
发布前,请确认生产环境的应用、Employee ID、出口 IP 和对象、字段及记录权限均已就绪。如需更换同步方案或数据源,请先评估现有任务流依赖,并在修改后重新执行验证。

