跳到主要内容

配置 纷享销客 数据源

最近更新 2026/11/03

纷享销客数据源用于通过离线同步读取 CRM 对象中的数据,并写入平台预置仓。本文介绍纷享销客端的应用授权、数据源配置、同步方案创建和任务流挂载。

使用限制与准备事项​

开始配置前,请确认以下限制和前置条件:

  • 纷享销客仅支持作为数据来源,不支持作为数据去向,也不会回写纷享销客。
  • 需由具备应用管理权限的企业管理员创建和维护自建应用,由 CRM 管理员配置访问员工的对象、字段和记录权限。
  • 准备一个正常启用、可长期维护的员工账号作为访问身份,并明确账号负责人和权限维护人员。
  • 确认需要同步的对象、字段和记录范围,以及平台运行环境能否访问企业所在云的纷享销客开放平台。
环境配置方式适用场景配置要求
不区分环境开发环境与生产环境共用连接配置准备一套应用凭据和 Employee ID,并确认访问权限符合要求
独立环境配置开发环境与生产环境分别维护连接配置分别准备可用凭据和 Employee ID,核对两个环境中的对象及字段权限,并分别完成连通性测试

在纷享销客中完成应用授权​

创建并启用企业自建应用​

  1. 使用企业管理员账号登录纷享销客网页版,进入管理后台。
  2. 打开 应用列表,选择 新建企业自建应用,填写应用名称、说明等信息并保存。
  3. 进入应用配置页面,启用开发者模式,按页面要求配置登录授权发起页域名和 IP 白名单。
  4. 确认应用在当前企业中处于启用状态,取得 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 和实际服务器出口核对凭据、接口、对象、字段及记录范围。应用已启用或能够取得访问令牌,并不代表员工已获得所需的全部数据权限。

创建纷享销客数据源​

  1. 进入 数据开发平台 > 集成 > 数据源,点击 + 数据源。
  2. 选择 纷享销客,点击 下一步,填写数据源名称和备注。
  3. 选择 不区分环境 或 独立环境配置。独立环境配置需要分别完成开发环境和生产环境的配置。
  4. 填写 API Domain、App ID、App Secret、Permanent Code 和 Employee ID。
  5. 在 连通性测试 中点击 测试。显示 可连通 后,点击 完成。

填写连接参数,并检查环境配置方式。

填写纷享销客生产环境连接参数
配置项说明
数据源名称当前空间内的数据源名称,需通过页面的名称及唯一性校验
备注选填,用于说明用途或维护信息
API Domain纷享销客开放平台的 API 域名,默认 open.fxiaoke.com;按企业所在云及平台支持情况配置
App ID企业自建应用的应用 ID,必填
App Secret上述应用对应的应用密钥,必填
Permanent Code上述应用对应的永久授权码,必填
Employee ID用于读取数据的员工 openUserId,必填;该员工需具有所需的数据权限

编辑已保存的数据源时,App Secret 和 Permanent Code 会以脱敏值显示;保留脱敏值即继续使用原凭据。需要更换时填写新值,并重新完成连通性测试。

提示

连通性测试通过后,仍需在离线同步方案中确认目标对象、字段和记录范围。独立环境配置下,应分别核对开发环境与生产环境的访问权限。

创建离线同步方案​

  1. 进入 数据开发平台 > 集成 > 离线同步,点击 + 集成方案。
  2. 在 数据来源 中选择 纷享销客及已创建的数据源。
  3. 选择 对象类型:预置对象或自定义对象。
  4. 在 来源对象 中按对象名称或 API 名搜索,选择需要同步的对象。
  5. 点击 数据预览,检查来源对象和可读取的数据内容是否符合预期。

选择对象类型和来源对象后,再预览数据。

选择纷享销客对象类型和来源对象
提示

切换对象类型后,原来选定的对象和字段映射会清空。请重新选择来源对象,并重新检查字段映射;来源对象未选定时,数据预览不可用。

字段映射与同步验证​

支持的字段类型​

字段类别支持的纷享销客字段类型
文本与单值引用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)本身不作为独立字段读取,其子字段可按各自类型选择。

配置与验证​

完成数据来源配置后,在 数据去向 中选择或创建平台预置仓的目标表,并建立字段映射。

提示

独立环境配置下,手动执行使用生产环境数据源配置。执行前请确认生产凭据、对象和字段权限,以及目标表均符合预期。

  1. 按业务需要设置目标表和写入方式。
  2. 在 字段映射 中,将需要读取的来源字段映射到目标字段。
  3. 不要将置灰字段作为可用字段配置,请根据提示调整需要同步的字段。
  4. 填写方案名称、负责人和备注后保存。
  5. 点击 手动执行,在执行记录中确认任务成功,再到目标表核对行数、字段和数据内容。

来源字段的名称用于识别业务含义,API 名用于区分对应字段。配置完成后,请逐项检查映射,避免将显示名称相近的字段错误关联。

以下为字段映射界面示例,请按实际业务核对字段对应关系。

纷享销客来源字段与目标字段的映射示例
现象检查项
连通性测试失败检查 API Domain、四项凭据及其对应关系,确认应用和员工账号未停用
提示 IP 未授权或访问被拒绝请部署维护人员核对实际服务器出口 IP,并检查是否已完整登记到应用 IP 白名单
对象列表为空或找不到目标对象检查对象类型是否正确,应用是否开放对象列表与查询权限,访问员工是否具有该对象权限
字段缺失或无法读取检查应用的对象描述权限和员工的字段读取权限,并确认对象结构是否发生变化
预览或同步的记录少于预期使用同一 Employee ID 核对员工的部门、负责人及共享范围,确认可读取的记录符合业务要求
来源字段置灰或无法读取查看字段提示,检查字段类型及其实际内容是否在支持范围内
开发环境正常、生产任务失败检查生产环境凭据、出口 IP、应用权限、员工数据范围,以及所选对象和字段是否可访问

挂载到任务流​

手动验证成功后,可将离线同步方案挂载到任务流,按调度周期自动执行。

  1. 打开已保存的离线同步方案,点击 挂载到任务流。
  2. 选择目标任务流。
  3. 填写节点名,选择执行模式,并按需设置负责人和备注。节点类型和集成方案会自动带出。
  4. 点击 创建节点并挂载。挂载成功后,可点击 前往任务流检查节点位置和上下游依赖。
  5. 保存任务流并完成发布;生产调度将使用生产环境的数据源配置。

发布前,请确认生产环境的应用、Employee ID、出口 IP 和对象、字段及记录权限均已就绪。如需更换同步方案或数据源,请先评估现有任务流依赖,并在修改后重新执行验证。

这篇文档对你有帮助吗?