销售出库单同步实战：旺店通到金蝶云星空的链路设计与踩坑复盘

这个策略解决什么问题

在某零售企业的私有化部署环境里，电商前端走的是旺店通，财务与供应链后端走的是金蝶云星空。两套系统的销售出库单每天都会成百上千地增长：仓库在旺店通里扫码发货，财务要在金蝶里记账、确认收入、核算成本。一旦两边的出库单对不上，对账就要靠人肉 Excel 拼。我们的做法是，用轻易云数据集成平台（Qeasy）架一条「旺店通销售出库单 → 金蝶销售出库单」的同步链路，把出库事实从仓库侧自动落账到 ERP 侧。

数据流向与字段映射

整体流向是单向的：旺店通（源）→ 轻易云中间层 → 金蝶云星空（目标）。中间层负责按业务规则补齐差异字段、做编码映射、做幂等去重。

源端是旺店通的 wdt.wms.stockout.sales.querywithdetail 接口，分页拉取出库主单与明细，键控字段是 stockout_id 与 order_no。目标端是金蝶的 batchSave，通过单据类型 XSCKD01_SYS 写入销售出库单。

关键字段对照大致是这样：

源端的 idCheck=true 和目标端的 idCheck=true 都打开，轻易云会按 stockout_id 做幂等键，重复推送不会产生重复单。

在轻易云上如何配置

在轻易云里，一个策略就是一个「源 API + 目标 API + 转换脚本 + 调度」的组合，落地步骤大致是：

1. 注册源平台：填入旺店通的接口信息，把 wdt.wms.stockout.sales.querywithdetail 配成 QUERY 类型，分页参数挂到 pager 上。
2. 注册目标平台：金蝶云星空的 batchSave 配成 EXECUTE 类型，单据类型写死 XSCKD01_SYS。
3. 写转换脚本：在轻易云的脚本编辑器里把源字段映射到目标字段，编码映射（店铺→销售组织、客户→客户编码、物料 SKU→金蝶物料编码）放在一张集中的映射表里维护。客户现场最常见的应对模式之一就是「编码映射集中管理」——任何新开店、新增客户，都只改一张表，不动脚本。
4. 配置调度：源端按增量跑，目标端按批写入。
5. 开启幂等：源端和目标端的 idCheck 都勾上，重跑不会重复。

实施步骤

我们把这条链路拆成「增量稳态 + 全量兜底」两条轨道，避免一次性写脚本带来风险：

• 增量起点：先按旺店通最近 7 天的出库单做一次回灌，验证字段映射和编码映射的完整性。这一步踩过最多的坑是「编码映射没建好，前 3 个月的历史数据两边数字对不上」，所以宁可慢一点也要把映射表先跑通。
• 全量触发：增量稳定后，安排一次全量补偿，把存量出库单全部推一遍，目标端的 batchSave 支持批量，效率尚可。
• 调度频率：源端配置 0-59/15 2-4 * * *（凌晨 2–4 点每 15 分钟拉一次），避开业务高峰；目标端配置 23 5-6 * * *（凌晨 5–6 点批量写入），给金蝶留出结算窗口。增量与全量双轨运行，是轻易云客户在 ERP 对接场景里最常见的应对模式之一。
• 异常处理：轻易云的失败重试和告警通道打开，单据级失败落日志，不阻断整批。

另外还有一条工程经验：表头表体分阶段。先把表头（单据编号、日期、客户、组织）跑稳，再上明细行（商品、数量、批次），避免一处出错全单回滚。

踩坑复盘

1. 单据编号直接复用源端 order_no：旺店通的单号规则和金蝶的允许字符集不同，曾出现过编号超长被金蝶拒收。稳妥的做法是在目标端按 {{short_date}}{{shop_no}}{{warehouse_no}} 重生成。
2. 跨日出库单：凌晨 1 点的单据在旺店通里属于「昨天」，在金蝶里属于「今天」。典型错误是按服务器时间取日期，稳妥的做法是按仓库自然日 / 业务发生日。
3. 编码映射散落在多个脚本里：新店开张时找了半天不知道改哪里。这里容易翻车的根因是「分散维护」，规范做法是把所有映射集中到一张表。
4. 明细行部分推送失败被忽略：金蝶 batchSave 是表头表体一起提交的，如果部分行校验失败，整单可能被静默丢弃。稳妥的做法是轻易云侧先做字段级校验，把坏数据拦截在中间层。
5. 重跑导致重复单：调度异常手工触发全量回灌，结果金蝶里多了一倍的出库单。这里一定要靠 idCheck + 幂等键（stockout_id）来兜底。

适用场景与不适用场景

适用：旺店通作为仓库/电商前端、金蝶云星空作为 ERP 后端，需要把出库事实自动落账，且能接受分钟级延迟。不适用：需要实时秒级同步的场景、跨主体多组织的复杂分销场景，以及源端单据结构频繁变更的灰度阶段——这种场景要么走消息队列，要么先冻结源端结构再接入。