轻易云
注册体验

销售订单基础资料同步实战:小满OKKICRM客户主数据查询策略详解

· 高金凤· 集成方案库· 6 次浏览· 约 5 分钟读完
吉客云小满OKKICRM销售订单客户主数据增量同步轻易云基础资料

这个策略解决什么问题

在销售订单集成链路里,客户主数据是所有订单写入的前置条件:没有干净的客户档案,下游的订单创建、收款核销、发货匹配都会带出脏数据。我们这次要讲的就是其中一个非常具体的策略——「查询小满客户」。它的任务很简单:按增量时间窗口从 CRM 拉客户资料,落到轻易云中间层,作为整个销售订单链路的基础档案底表。

数据流向与字段映射

数据流向非常清晰:

源系统(小满 OKKI CRM)→ 轻易云集成平台(Qeasy 中间层)→ 后续销售订单写入策略消费。

源端的查询接口是 GET /v1/company/updates,分页参数 start_index 默认 1、count 默认 20,removed=0 表示不带已删除,all=1 表示查询所有客户,group_id 可选(用于按客户分组过滤),date 作为增量起点。响应中唯一标识客户的是 company_id,序列号是 serial_id。

目标端在轻易云一侧是写入空操作(POST),用于把客户档案沉淀到中间层表 id 字段,供后续销售订单策略按 company_id 关联引用。

下面这张表是我们在客户现场整理出来的关键字段对照:

业务含义源端字段目标端字段备注
客户唯一标识company_idid主键,订单关联键
客户序号serial_idserial_id序列号,辅助排序
客户名称namename名称标准化在中间层处理
分组 IDgroup_idgroup_id可选,过滤条件
删除标记removedremoved增量窗口控制
更新时间dateupdated_at增量起点

这里有一个容易被忽略的设计点:编码映射集中管理。我们把「小满 company_id ↔ 轻易云 id」这一对照,放在轻易云的映射表里统一维护,而不是写死在每一条订单写入策略里——这样后续扩展第三方 CRM 时,只要追加映射行即可。

在轻易云上如何配置

在轻易云数据集成平台里,这个策略属于典型的 QUERY_ONLY 类型,配置上有几个要点:

  1. 数据源注册:把小满 OKKI CRM 注册为一个平台接入点,认证信息(密钥、租户标识等)在轻易云的连接器里配置,这里不展开细节,但要提醒一句——密钥不要落到策略配置里,放连接器层托管。

  2. 请求参数模板:把分页参数 start_index、count、removed=0、all=1 做成模板,首次请求 start_index=1,后续根据响应里的 total 或 has_more 翻页。增量起点 date 来自轻易云维护的游标变量(上一次同步成功的最大更新时间)。

  3. 目标写入:目标端的「写入空操作」并不是真的空——它把客户档案落到轻易云的中间层表,字段命名沿用源端,后续订单策略通过 JOIN 消费。这里我们采用「表头表体分阶段」的应对模式:客户档案只做头表,后续订单再带明细,避免一次性把客户、联系人、地址揉在一起。

  4. ID 校验:目标端 idCheck=true 表示主键去重和幂等检查——同一个 company_id 多次同步不会重复插入,这是数据一致性的兜底。

  5. crontab 与依赖:源策略本身的 crontab 在示例里写的是 */20 8-22 * * *,表示业务时段每 20 分钟一轮;在轻易云里我们用调度中心配置,首次全量触发 + 后续增量双轨:上线当晚手动跑一次全量,把历史客户档案补齐,之后进入 */20 的增量节奏。

实施步骤

分阶段调度是这个策略能不能稳定运行的关键。我们在客户现场的实施顺序是这样的:

  • Step 1 · 全量起点:上线前,在轻易云里手动触发一次全量查询,removed=0&all=1 拉齐所有现存客户。这一步是为了把中间层表先填好基线。
  • Step 2 · 游标初始化:全量完成后,轻易云自动记录最大 date 作为增量游标,落到一个状态变量里。
  • Step 3 · 增量调度:进入 */20 8-22 * * * 的增量节奏,每轮用上一次游标往后推一页。
  • Step 4 · 翻页控制:根据响应判断是否还有下一页,有就继续翻,没有就刷新游标并等待下一轮。
  • Step 5 · 依赖衔接:这个策略在 depends_on 里是空的,意味着它必须先于销售订单写入策略跑完。我们用轻易云的策略编排,把客户档案同步放在订单写入上游。

踩坑复盘

  1. removed 参数忘了传,导致历史已删除的客户又被拉回来。典型错误是漏看默认值,稳妥的做法是在轻易云请求模板里显式写死 removed=0。
  2. date 增量游标没保存,每次都全量拉。客户量一大接口就会超时。我们用轻易云的变量池持久化游标,失败重试时也不丢。
  3. all=1 与 all=0 没分清,公海私海数据混在一起。如果业务上销售只看私海客户,all 必须传 0;但这又会漏数据,稳妥的做法是先 all=1 拉齐档案,再在订单写入侧按业务规则过滤。
  4. company_id 在轻易云中间层没建唯一索引,导致同一客户多份档案,订单关联时随机命中。这里要靠目标端 idCheck=true + 数据库唯一约束双保险。
  5. crontab 写成 1 1 1 1 1——这是目标端示例里那行奇怪的表达式,显然不是正常调度。踩坑提醒:源策略的调度才是生效调度,目标端的 crontab 字段在「写入空操作」场景下基本不参与执行,别被示例值误导。

适用场景与不适用场景

适用:CRM 侧客户主数据需要按增量沉淀到中间层、供订单/收款/发货等多下游消费,且客户量在十万到百万级。不适用:需要实时(秒级)同步客户变更的场景——*/20 的节奏撑不住;也不适用 CRM 与 ERP 是同库直连、不需要中间层的轻量场景。

本文为原创内容,转载请注明出处:https://www.qeasy.cloud/insights/solutions/strat-p2ea595-okkicrm-6190-n32c9d889-994c52b4

评论