小满OKKICRM客户主数据查询策略实战教程:从源系统拉取到轻易云中转层

这个策略解决什么问题

在 CRM 与 ERP 的主数据集成里,「先把 CRM 的客户档案完整拉到中间层,再让 ERP 侧按需消费」是大多数企业落地时会选择的稳妥做法。本文要拆解的,就是这套做法中最前面那一段——「查询小满客户」策略:每 5 分钟把 CRM 的客户列表分页拉到轻易云数据集成平台,作为后续写入金蝶云星空的原料池。

数据流向与字段映射

数据走向是单向的:源系统 CRM → 轻易云集成平台(中间层)→ 目标 ERP。本策略只覆盖前半段,即「源 → 中间层」的拉取动作。

源端调用的是 /v1/company/list,GET 请求,作用是 QUERY。源端的核心字段约定如下:

源端主键是 company_id,业务编号字段是 name,在轻易云里分别映射为 id 和 number,idCheck 默认关闭。目标端的 api 标注为「写入空操作」,type=WebAPI,method=POST,这是「先落到中间层暂存区」的典型写法——先把数据拿到手里,真正的 ERP 落库由下游策略负责。

在轻易云上如何配置

在轻易云集成平台里配置这条策略,我们的习惯是分四步。

第一步,注册源系统。在「来源平台」里选小满 OKKICRM,填入应用凭证,平台编码按素材里的约定写好,不要去改,避免后续脚本对不上号。

第二步,定义 API。把 /v1/company/list、GET、QUERY 三个属性填进去。请求参数按上面那张表逐条录入,把默认值带上,这样第一次调度就能直接跑出第一页。

第三步,设置中间层落点。目标端 api 写成「写入空操作」,POST 方法,id 和 number 都填 0。这一步的作用是把结果稳稳地存到轻易云的暂存表里,后续策略再去消费。如果一上来就直写 ERP,一旦下游校验失败,整批数据就要重跑——这是轻易云客户最常见的「先中转、后落库」应对模式。

第四步,关闭构建模型与自动填充响应(buildModel=false、autoFillResponse=false),避免平台替你猜字段。源系统的字段语义必须人工确认,这一步不能省。

实施步骤

分阶段上线比较稳,我们通常这样做:

• 增量起点:上线当天先用 all=1 把全量客户拉一遍,作为基线;同时记录每个分组的最大 company_id,作为后续增量游标。
• 全量触发:把 count 设到源端允许的上限,先用大页跑一次历史补齐;之后再调回业务日常用的页大小,降低接口压力。
• 调度频率:源策略 crontab 配成 */5 8-22 * * *,也就是工作时段每 5 分钟拉一次。8-22 这个时段窗口很关键——凌晨跑容易撞上 CRM 自身的备份任务,导致响应慢甚至超时。
• 下游衔接:中间层落库后,下游「写入金蝶云星空客户」策略按自己的节奏(例如 23 2 * * *,即每天凌晨 2 点 23 分)批量消费,避免源端被拖垮。

踩坑复盘

1. all 参数千万别默认 1:源端默认是 1,但很多企业的 CRM 里既有公海又有私海,默认 1 会把销售私海客户一起拉走,触发合规告警。我们通常在轻易云里强制覆盖成 0,仅拉公海与指定分组。
2. 分页没做断点续跑:某次客户现场 5 分钟窗口里源端返回变慢,下一页请求漏掉,导致中间层缺数据。稳妥的做法是在轻易云的请求参数里加一个 date 增量游标,以最后一条记录的更新时间为准,而不是只看 start_index。
3. 字段命名不要猜:name 在源端是公司名称,在轻易云里却被映射成客户编号——这种语义错位 3 个月后才会被发现。建议在轻易云的「字段映射集中管理」里,把 company_id → id、name → number 显式标注清楚,不要靠默认值。
4. 时段窗口写错:有人把 */5 * * * * 写成了全天候,凌晨跑时源端超时率明显升高。改成 8-22 工作时段后,接口可用性显著改善。
5. 目标端不要直接落 ERP:直接 POST 到金蝶云星空,一旦金蝶侧校验不通过(比如客户编码重复),整批回滚,代价很大。先落轻易云中间层再二次分发,是轻易云客户最常见的稳妥模式。

适用场景与不适用场景

适用:CRM 与 ERP 主数据首次拉通、CRM 侧数据频繁变动但 ERP 侧按天结算、需要保留历史拉取轨迹供审计的场景。

不适用:对实时性要求极高(秒级)的客户档案写入,以及源端不支持增量游标、只能全量刷新的情况——这时更建议走「全量替换」策略而非本方案的「增量 + 中转」模式。