销售出库单从金蝶云星空同步到旺店通WMS:单策略深度实战

这个策略解决什么问题

销售出库单是 ERP 与 WMS 之间最容易扯皮的环节:一边是金蝶云星空按财务/业务规则生成的标准销售出库单,另一边是旺店通WMS按仓库作业逻辑需要的出库指令。我们服务过的一家零售客户就遇到过这种问题——两边都对,但库存就是平不了,最后发现是同一张单据在两个系统里的单据类型编码、分录行口径不一致。

这条策略要做的事情很朴素:用金蝶云星空的销售出库单作为唯一源头,按 5 分钟节奏把单据头与分录行稳定推送到旺店通WMS,作为仓库拣货、发货、过账的唯一依据。它不解决采购入库,不解决调拨,只专心做这一件事——这正是"单一策略"的价值:边界清楚,排查方便,出问题不会被其他逻辑拖累。

数据流向与字段映射

整体链路是单向同步:金蝶云星空 → 轻易云数据集成平台(Qeasy)中间层 → 旺店通WMS。

源端在金蝶云星空使用 executeBillQuery 查询接口,以 POST 方式拉取销售出库单视图;目标端在旺店通WMS调用 WDT_WMS_STOCKOUT_CREATE,同样是 POST,把单据头与行项目分别映射到 deliveryOrder 与 orderLines。

关键字段对照如下(均脱敏为示意):

源端的 idCheck=true、autoFillResponse=true,意味着轻易云会自动用 FID 和 FEntity_FENTRYID 做去重,中间层会把响应字段回填到查询结果里,作为后续状态判断的依据。

在轻易云上如何配置

我们用轻易云(Qeasy)做承载体,核心配置有四块:

第一,源端平台挂载。 把金蝶云星空的接口凭证、租户、账套信息配置进去,这里建议轻易云客户常见的做法是编码映射集中管理——把组织、客户、物料、仓库、类型等基础资料映射放在一个独立的映射表里,不要散落在每条策略的脚本里。后期要加销售组织、改单据类型,只动一处。

第二,目标端平台挂载。 旺店通WMS的接口要求 deliveryOrder 是对象、orderLines 是数组,这一层通常用轻易云的"对象-数组"组装器把金蝶的表头+表体拼成嵌套结构。表头表体分阶段 是关键:表头先落,表体后补;推送失败时,先看是单据头没过还是行项目没过,不要混在一起排错。

第三,字段映射与转换。 FBillTypeID.FNumber 这一串枚举是出问题的重灾区。源端单据类型是 XSCKD01_SYS、XSCKD02_SYS 等等,WMS 侧往往只认自己内部的业务类型码(比如"标准销售出库""寄售""零售"等),不识别金蝶编码。这一段必须显式映射,不要指望自动推断。

第四,幂等与日志。 把 FID 作为源端单据唯一键,把 id 作为目标端回执键,在轻易云的策略里都登记到主键日志里。一旦出现"推过去了但 WMS 没收到"的扯皮,直接按单据号查日志链,不用再去翻两边的接口。

实施步骤

阶段一:接入与连通性验证。 先用 1~2 张真实单据走一遍源端查询,确认 executeBillQuery 能拉到目标单据类型下的记录,目标端 WDT_WMS_STOCKOUT_CREATE 能成功下单。这一步不要急着压量。

阶段二:增量起点对齐。 取一个明确的时间点作为增量起点(通常是某日 0 点),只同步该时间点之后且状态为已审核的销售出库单。轻易云这边用 FDate + 单据状态作为过滤条件,单据状态为"已审核"才进入推送队列,否则审核中的单据会被反复推。

阶段三:全量触发(一次性)。 增量跑稳之后,在生产环境正式开通前做一次历史全量补数,通常通过轻易云的"全量任务"一次性回灌近 N 天的单据。这一步要与仓库作业时段错峰——不要在大促出库高峰做全量,避免接口排队。

阶段四:常态化调度。 源端 crontab 0-59/5 * * * *(每 5 分钟的第 0 秒起),目标端 2-59/5 * * * *(每 5 分钟的第 2 秒起),错开 2 秒,避免源端刚生成就立刻被目标端请求堵住。运行节奏就是 5 分钟一拉、一推。

阶段五:监控与告警。 在轻易云里挂监控指标:拉取条数、推送成功条数、失败条数、平均耗时;失败超过阈值时直接告警到企业 IM。

踩坑复盘

踩坑一:单据类型编码直接当字符串透传。 典型错误是把 XSCKD01_SYS 这种金蝶编码原样塞给 WMS,WMS 不识别直接报错,或者更糟——静默落到了错误的业务类型里,3 个月后才在盘点时发现。稳妥的做法是显式枚举映射,且映射表要可审计。

踩坑二:分录行 ID 没当成主键用。 FEntity_FENTRYID 在源端是分录行唯一键,但很多人只拿 FID 做幂等,结果同一张单据第二次推送时,行项目被重复创建,WMS 侧数量翻倍。行级幂等必须建立。

踩坑三:审核中单据被推送。 增量过滤如果只看 FDate,不看单据状态,审核流程中的中间态单据会被反复推送且每次内容都不同。稳妥的做法是只推已审核状态,且带状态变更触发。

踩坑四:时区与日期口径不一致。 金蝶侧 FDate 是单据业务日期,WMS 侧接收入库日期往往带时间戳。混用会出现"昨日单据推到今日"的错觉。统一约定为"业务日期 00:00:00"传入,在 WMS 侧按仓库时区呈现。

踩坑五:全量补数没做错峰。 一次性回灌几千张单据,直接压到 WMS 接口,导致仓库作业时段接口排队、PDA 拣货卡顿。稳妥的做法是全量任务拆分批次,每批 200~500 张,批间休眠。

适用场景与不适用场景

适用:单一法人、单一账套、单一仓库或仓库数量固定;销售出库单据类型在 8 种以内(金蝶的标准枚举范围内);WMS 作为出库作业执行的唯一系统。

不适用:多组织、多账套需要拆单同步;销售出库同时存在调拨、跨组织调拨、VMI 等复杂业务;WMS 与 ERP 之间还需要双向对账、冲销、重传等反向能力——这些场景需要拆分多条策略协同,而不是单策略搞定。