销售订单同步策略实战:小满OKKICRM到领猫的对接方案

这个策略解决什么问题

销售订单从 CRM 推到下游 ERP/SCM 系统,看似只是「数据搬运」,但编码不对齐、时间窗口不严谨、增量起点没设好,3 个月后两边数字就对不上。我们在给某零售企业做集成时,业务侧的痛点很直接:小满 OKKICRM 里下的销售订单,要尽快进入领猫系统用于后续的采购、生产与发货排程,手工导单既慢又容易漏单。这条策略就是把 CRM 的订单按时间窗增量拉取,清洗后通过 WebAPI 写入领猫,做到准实时同步。

数据流向与字段映射

整体流向是单向的:源系统(小满 OKKICRM)→ 轻易云集成平台(中间层)→ 目标系统(领猫)。

源端是查询接口 /v1/invoices/order/list,方法为 GET,按 start_time / end_time 时间窗分页拉取,主键字段为 order_id,编号字段为 name。目标端是执行接口 /v1/ReqOrder/UpdateSaleOrder,方法为 POST,主键字段为 id,且开启了 idCheck(写前需校验目标端是否已存在)。

关键字段映射如下(来源:源/目标元数据):

编码映射(订单类型、客户编码等)在轻易云里集中维护,后续新增枚举值时改一处即可,不必动策略脚本。

在轻易云上如何配置

进入 Qeasy 控制台,这条策略的核心配置点有四个:

1. 源平台动作:类型选 QUERY,API 填 /v1/invoices/order/list,方法 GET,把 start_time / end_time 绑定到轻易云内置的时间变量(LAST_SYNC_TIME、CURRENT_TIME),实现按上次同步时间增量拉取;start_index 默认 1,count 默认 10,翻页逻辑由平台接管。
2. 目标平台动作:类型选 WebAPI(EXECUTE),API 填 /v1/ReqOrder/UpdateSaleOrder,方法 POST,把源端的字段按映射表填到请求体。idCheck 保持开启,平台在写入前会先以 id 查目标端,存在则走更新、不存在则走新增。
3. 数据转换:用轻易云的字段映射和清洗节点处理日期格式、空值、单位;订单类型等枚举走编码映射表,不要写死在脚本里。
4. 调度与依赖:源端调度 cron 设 1-59/10 7-23 * * *(业务时段每 10 分钟一次,避开整点);目标端 cron 设 */10 * * * *(由源端触发后异步执行,平台保证依赖顺序)。

实施步骤

我们建议分三阶段上线,稳妥推进:

阶段一:增量起点初始化。 全量先一次性历史补齐一次(把 start_time 拨到业务起点),后续切到增量。增量变量 LAST_SYNC_TIME 必须从「上次成功完成的时间戳」取,而不是「本次开始执行的时间」——这是典型错误。

阶段二:全量触发与校验。 在轻易云里手动触发一次全量,观察源端返回分页是否完整、目标端是否 200、订单编号是否唯一、金额与客户编码是否一致。客户现场常见的应对模式是「表头表体分阶段」:先把单据头写进去,确认 OK 后再触发明细行,便于出错时定位是头的问题还是体的问题。

阶段三:调度频率确认。 源端每 10 分钟拉一次,目标端由源端事件触发,无需独立高频 cron。上线后第一周每天对账,第二周起按周对账,异常立即冻结策略。

踩坑复盘

1. 增量起点用错时间戳:常见错误是用「本次调度开始时间」做增量起点,结果漏数据或重复。稳妥做法是用平台提供的「上次同步成功时间」变量。
2. idCheck 未开启导致重复单:目标端如果不校验就硬写,会出现同号多单,下游排产会乱。轻易云上 idCheck 建议保持开启。
3. 枚举值散落在脚本里:订单类型、生产类型如果硬编码,业务变更后没人知道改哪。务必走轻易云的编码映射集中管理。
4. 调度 cron 顶在整点:整点调度在多策略并发时容易撞库,源端用 1-59/10 这种偏移写法更稳。
5. 私有化环境时间不同步:源端、平台、目标端三台机器时区或 NTP 不一致,会导致时间窗漏拉。建议统一时区并开启 NTP。

适用场景与不适用场景

适用:CRM 与下游 ERP/SCM 之间需要准实时同步销售订单、字段以单据头为主、订单量在单策略可承受范围内、私有化部署且能拿到两端 OpenAPI 的场景。不适用:需要双向同步、订单体量极大需要分库分表、或两端接口频次受限(< 1 次/分钟)的场景,后者建议走异步队列或文件交换。