销售出库同步实战教程:从聚水潭到金蝶云星空的增量闭环

这个策略解决什么问题

在一次零售企业的供应链集成项目里,前端电商 ERP 每天会生成大量"已出库"状态的销售出库单,财务和供应链需要在后端 ERP 中以销售出库单为依据记账并扣减库存。最朴素的做法是手工导单,但订单量一上来,人工就扛不住,而且容易出现两边库存数字对不上的尴尬。这条策略的核心,就是把前端已确认的销售出库单按增量方式搬到后端,让出库数据当天可见、库存扣减有据可循。

数据流向与字段映射

整体流向是:源系统(聚水潭)→ 轻易云数据集成平台(Qeasy)→ 目标系统(金蝶云星空)。轻易云在这里既是搬运工,也是翻译官。

源端调用的是聚水潭的 jushuitan.saleout.list.query 接口,按 修改开始时间 / 修改结束时间 拉取增量,时间间隔不超过 7 天,只取状态为 Confirmed(已出库)的单据,分页参数 page_index 从 1 开始,page_size 默认 25。

目标端写入金蝶云星空的 batchSave 接口,单据类型 XSCKD01_SYS,日期、销售组织、客户、部门等基础资料字段由变量带入。

关键字段对照表:

shop_id 到 FCustomerID 的映射是这一步最容易翻车的地方,我们统一放在轻易云的编码映射中心维护,源端增店铺时只改一处。

在轻易云上如何配置

在轻易云数据集成平台(Qeasy)中,这条策略属于典型的「源 QUERY + 目标 EXECUTE」组合,几个关键配置点:

• 数据源注册:填好聚水潭奇门平台的 appKey / appSecret,绑定授权店铺范围。
• 目标系统注册:选金蝶云星空,录入组织编码、应用 ID 等基础信息。
• 源接口:选 jushuitan.saleout.list.query,把 start_time、end_time、status 三个入参用变量绑定,status 固定为 Confirmed。
• 目标接口:选 batchSave,单据类型写死 XSCKD01_SYS,日期和单据编号用变量带入。
• 映射规则:表头字段做一对一映射,表体行项目拆开处理;客户编码走「编码映射集中管理」,而不是在脚本里硬编码。
• 去重与幂等:用 io_id 作为幂等键,目标端开启 idCheck,同一张单据重复推不会被二次生成。

实施步骤

我们一般建议客户按「增量起点 → 全量触发 → 调度频率」三步走。

第一步:确定增量起点。 与业务方约定一个明确的时间戳,例如 2024-01-01 00:00:00,所有早于此时间的单据走历史全量通道,之后的单据走增量通道。增量变量用 {{LAST_SYNC_TIME|datetime}} 和 {{CURRENT_TIME|datetime}} 控制窗口。

第二步:全量触发。 在轻易云里手动跑一次历史窗口,把存量已出库单全部补齐,并和源系统对一遍总数。这一步不能省,否则财务月结时数字对不上,排查起来非常耗时。

第三步:常态化调度。 源端用 */23 * * * *,每 23 分钟拉一次增量;目标端用 */40 * * * *,每 40 分钟往金蝶推一次,两者错峰避免堆积。运行一段时间后,我们再根据数据量把频率收敛到 15 分钟一次。

踩坑复盘

1. 时间窗口超过 7 天直接报错。 聚水潭接口要求开始/结束时间间隔不超过 7 天,所以调度间隔务必小于 7 天,否则会断流。
2. 店铺编码没集中管理。 早期有客户把 shop_id → FCustomerID 写在脚本里,半年后开了新店,脚本改了三处才找全,后来统一收口到编码映射中心。
3. 表头表体混在一轮跑完。 销售出库单的表体行项目比较多,建议先稳跑表头,再单独配表体,采用「表头表体分阶段」策略,失败定位快很多。
4. 重复推送生成重复单据。 一定要开 idCheck,否则网络抖动重试时,后端会出现两张内容相同的销售出库单,带来对账麻烦。
5. 增量与全量不区分。 把两者跑在同一个通道里,一旦时间戳错位就会覆盖历史。建议在轻易云里建两条独立策略:一条全量,一条增量,各自维护水位。

适用场景与不适用场景

适用: 电商前端是聚水潭、后端财务/供应链是金蝶云星空,且单据量在日均数千单以内的零售或分销场景。 不适用: 需要实时秒级同步的仓配一体化业务(应走消息队列或 WMS 直连),以及非已确认状态的预出库单(本策略仅同步 Confirmed 状态)。