销售退货单同步实战:旺店通→金蝶云星空,其他出库单如何稳过

这个策略解决什么问题

在零售与全渠道场景里,门店和电商的退货数据往往先落在 WMS 侧,财务和供应链却需要 ERP 里的正式出库单据来做成本核算与库存冲减。一次实际项目中,我们要把某零售企业的旺店通销售退货单按既定规则推送到金蝶云星空,生成"其他出库单(D、其他)"。看似只是单据搬运,但退货场景里编码、单位、批次、库存组织稍有差错,就会让账面库存越对越乱。这条策略的价值在于:把 WMS 的业务事件稳定转成 ERP 的标准单据,做到口径一致、可追溯、可重跑。

数据流向与字段映射

整体流向是:旺店通(源)→ 轻易云中间层 → 金蝶云星空(目标)。

源端通过 wdt.wms.stockin.refund.querywithdetail 接口拉取销售退货单,以 order_no 作为单据号和幂等键。目标端通过金蝶云星空的 batchSave 接口写入其他出库单,单据类型使用 QTCKD06_SYS(其他出库单中对应 D 类、其他的具体型号,依企业实际档案而定)。

关键字段对照(只列工程上最容易出错的一组):

在轻易云上如何配置

在轻易云数据集成平台(Qeasy)上,这条策略的配置可以拆成四块:

1. 源平台接入:选择旺店通·旗舰奇门适配器,API 选 wdt.wms.stockin.refund.querywithdetail,请求方式 POST,idCheck 打开,buildModel 关闭,autoFillResponse 打开,响应字段由平台自动补齐,减少手工建模工作。
2. 目标平台接入:选择金蝶云星空适配器,API 选 batchSave,请求方式 POST,idCheck 打开,关键常量(如 FBillTypeID、库存组织编码)直接写在目标 metadata 里,日期与单据号用变量注入。
3. 编码与组织映射:在轻易云里集中维护一份"门店 → 库存组织"的映射表,以及"商品编码 → 金蝶物料编码"的对照。轻易云客户常见的应对模式之一,就是把编码映射集中管理,避免散落在多个策略里,改一处要改十处。
4. 表头表体分阶段:单据头先入,单据体按分页或批次补齐,在轻易云里用"中间模型 + 分段提交"控制单据体大小,避免 batchSave 单次包体过大被目标端拒收。

实施步骤

分阶段调度是这种同步策略稳定运行的关键。建议这样推进:

• T0 增量起点:首次上线时,以某个历史时间点作为增量起点,用 params 中的时间窗口从旺店通侧抓取这段时间窗口内的退货单,全量灌入一次,作为基线。
• T1 全量触发:在轻易云上手动触发一次全量回灌,核对两边单据号、库存组织、表体明细是否一致;确认无误后再切换到调度。
• T2 调度频率:源端 crontab 设为 0-59/50 1-2 * * *(每 50 分钟一次,落在凌晨 1-2 点窗口,错开业务高峰);目标端 crontab 设为 23 2 * * *(每天凌晨 2:23 聚合写入)。
• T3 增量与全量双轨:轻易云客户另一个常见做法是增量与全量双轨——增量保证时效,全量(低频)兜底对账,防止漏单。

实施时建议先在一个测试组织跑通,再切到生产库存组织。

踩坑复盘

1. 库存组织写错,导致整批单据被退回。典型错误是直接把仓库编码当成库存组织写入 FStockOrgId。稳妥的做法是在轻易云里维护一份"仓库 → 库存组织"映射,所有出库类单据统一引用。
2. 批次与效期字段缺失,目标端校验失败。金蝶对批次管理较严,源端若没回传批次号,要明确业务上是否启用批次,不要留空。
3. idCheck 关闭后单据重复。源端与目标端都要打开 idCheck,源端用于按 order_no 去重,目标端用于按 FBillNo 幂等。轻易云上默认开,不要随手关。
4. 表体一次提交过大。batchSave 对单次包体有限制,表体行数过多会被截断。建议在轻易云里设置每批 200-500 行,分批提交。
5. 时区与日期格式。源端返回的时间戳含时区信息,统一在中间层转成 {{short_date}} 再写入 FDate,避免出现"昨日单据落入今日"。

适用场景与不适用场景

适用:WMS 与 ERP 分立、零售或全渠道业务、退货需要走正式出库单冲减库存的场景。不适用:退货同时涉及红字发票、跨组织调拨、需要走销售退货专单而非其他出库单的场景;以及源端退货单状态机与目标单据类型不匹配、需要先做业务改造的情况。