销售订单从聚水潭同步到金蝶云星空:一条策略的实战拆解

这个策略解决什么问题

电商前端在聚水潭里完成审单、打印、发货,后端财务和供应链核算跑在金蝶云星空上。两边不打通,就会出现"仓库已经发出去了,ERP 里还是待发货"的尴尬:库存对不上、成本结不出、客服查单只能靠截图。

这条策略要做的就是——把聚水潭里已确认出库的销售订单,按修改时间增量拉到金蝶云星空生成销售出库单,让前端履约和后端核算在同一条数据线上。

数据流向与字段映射

整体走"源 → 中间层 → 目标"三段式,轻易云(Qeasy)集成平台作为中间层负责取数、转换、落库。

源端只取 status=Confirmed 的单据,目标端单据类型固定为 DSXSCKD(电商销售出库单)。商品、客户、店铺、快递公司这几类基础资料,不在本策略里做映射,而是通过前置的客户/物料策略先在中间层建好映射表,这里用 findCollection 反查——这是轻易云客户常见做法:编码映射集中管理,避免散落在每个策略里。

在轻易云上如何配置

源端配置要点:

• API 选 orders.out.simple.query,POST 调用;
• 分页参数 page_index / page_size(单页最大 25,这里设 100 是按文档范围压住);
• 增量窗口用 {{LAST_SYNC_TIME|datetime}} 到 {{CURRENT_TIME|datetime}},配合调度时间;
• number 字段填 io_id,id 填 o_id,打开 idCheck,重复单据自动跳过;
• 响应体 autoFillResponse 打开,后面写表体时直接拿 items。

目标端配置要点:

• API 选 batchSave,POST;
• 单据类型 FBillTypeID=DSXSCKD,单据编号 FBillNo={{o_id}};
• 销售组织 FSaleOrgId 用 _findCollection 从辅助资料表反查 shop_id;
• 表头和表体建议分阶段写入:先 batchSave 表头拿到返回 id,再循环写表体,失败可重试单条。

实施步骤

1. 基础资料先行:客户、商品、店铺、快递公司走前置策略先落映射表,本策略不重复造轮子。
2. 增量起点:首次上线用全量触发,把历史已出库单据按 io_id 去重一次性补齐;之后切换为增量,起点取上次同步成功时间。
3. 调度频率:源端 cron 10 7-22/3 * * *(每 3 小时一次,7-22 点覆盖主要出库时段),目标端 cron 40 7-22/3 * * *(延后 30 分钟,留出取数 + 转换 + 落库的时间窗),两端错峰。
4. 幂等与回写:以 o_id 作为幂等键,目标端写入成功后把金蝶返回的 id 回写到中间层,便于人工排查和失败重放。
5. 监控与告警:轻易云控制台看累计处理条数、失败条数;失败订单进异常队列,人工处理后补跑。

踩坑复盘

• 增量窗口不能跨度过大。聚水潭接口要求起始/结束时间间隔不超过 7 天。一旦调度漏跑或被跳过,下一次同步窗口会被截断,数据会丢。稳妥做法是给调度加超时告警,出现漏跑立刻手工补。
• 店铺编码 ≠ 销售组织。前端店铺 id 是聚水潭自维护的,金蝶那边是组织维度。直接传值金蝶一定拒收。一定要走 findCollection 反查,而且映射表要随组织调整同步更新。
• 表头表体一起 batchSave 容易翻车。一旦表体某一行校验失败,整单回滚,排查时只看得到错误码看不到具体行号。建议分阶段:先写表头,再循环写表体,失败可定位到行。
• 已作废单据(Cancelled)要过滤。源端 status 默认会带多种状态,如果不显式传 Confirmed,会把作废单也同步过去,导致金蝶库存虚增。
• 时区与日期格式。聚水潭返回的 io_date 是字符串,跨时区客户要把时区统一到 ERP 端,否则 FDate 会偏一天,影响日结。

适用场景与不适用场景

适用:电商前端在聚水潭、后端 ERP 在金蝶云星空,需要把已出库订单按增量方式同步到 ERP 生成销售出库单,体量在每天几千到几万单。不适用:需要实时(秒级)同步出库状态的业务、跨多个 ERP 账套、或者聚水潭侧走奇门通道的订单(那是另一套策略)。