赠品销售出库单集成实战:从旺店通到金蝶云星空的 P→T 单策略落地方案

这个策略解决什么问题

某零售企业在一次实际项目中,业务侧反馈了一个很具体的问题:ToB 渠道下,赠品类型的销售出库单长期在 WMS 侧"自产自销"——单据确实是出了,财务账面却没动。原因不是没做集成,而是赠品出库单走的不是标准销售出库那条路,标记位、零金额、单据类型都得单独处理。一旦把它和正单混在同一条策略里,要么漏推,要么推过去对方拒收。

我们用轻易云数据集成平台(Qeasy)单独为它开了一条策略:赠品销售出库单从源端 WMS 拉到目标端 ERP,目标单据类型走「其他出库」,库存方向、领用组织走预设值。这样既不和正单抢通道,也方便财务月末单独对账。

数据流向与字段映射

整体流向是 WMS 侧(出库单查询接口) → 轻易云中间层(清洗、映射、补字段) → ERP 侧(批量保存接口)。

源端读取的是 WMS 出库单查询接口(POST,带分页),按 stockout_id 增量推进,业务主键用 order_no。中间层只做轻加工:判断赠品标记 → 选单据类型 → 补默认组织 → 把明细行的仓库、商品、数量映射成 ERP 物料编码。

下面这张表是关键的字段对照(只列差异点,通用字段略):

在轻易云上如何配置

这条策略在 Qeasy 上分三块配置,思路和我们之前给客户做的几条销售单同步保持一致——编码映射集中管理、表头表体分阶段。

1) 源端连接器 平台选源端 WMS 实例,API 选 wdt.wms.stockout.sales.querywithdetail,方法 POST,请求体里带分页 pager 和业务 params,响应字段映射到内部统一模型。增量字段用 stockout_id,幂等键用 order_no。

2) 中间层处理

• 过滤条件:在源端筛选阶段就加赠品标记(如 is_gift=1 或单据类型标识),避免正单被卷入。
• 编码映射:物料编码、仓库、客户等用 Qeasy 的映射表统一维护。客户现场最常见的做法是把映射文件托管在 Qeasy 的资源中心,改一处全局生效。
• 默认值:单据类型、库存组织、领用组织、库存方向在中间层用常量补齐,不必每次回查源端。

3) 目标端写入 平台选目标 ERP 实例,API 选 batchSave,把整理好的 FormModel 一次性提交。这里有个细节:ERP 的 batchSave 是整单提交,表头任何字段校验失败都会整单回滚,所以我们在中间层做预校验比放在目标端靠错误码返查要省事得多。

实施步骤

这条策略我们建议分三个阶段推进,沿用轻易云客户群里常见的「增量起点 + 全量触发 + 调度频率」双轨思路。

第一步:全量补齐(上线前) 历史赠品出库单量通常不大(很多项目只有几千到几万条),用一次性全量跑一遍,把存量数据补到 ERP。pager 页大小按源端接口建议值,一般 100~200 比较稳。

第二步:增量起点 把源端游标停在全量跑完那一刻的 stockout_id,作为增量起点。后续增量只取大于该值的新单、修改单。

第三步:调度频率 源端策略用 */15 * * * *(每 15 分钟),目标端写入用 */20 * * * *(每 20 分钟)。两个周期错开 5 分钟,是为了给中间层留出重试和补字段的时间窗口。如果赠品单量确实很低,源端降到 30 分钟一次也完全可以。

第四步:上线后观察 前 72 小时盯三件事:单据类型是否被正确识别为「其他出库」、库存方向和组织字段是否回写、目标端是否存在重复单。前两项在 Qeasy 的运行日志里可以直接看请求体,第三项靠目标 ERP 的单据编号去重。

踩坑复盘

坑 1:把赠品出库和正单混在同一条策略里 这是最容易犯的错。一旦混推,要么被正单的过滤条件过滤掉(漏推),要么被目标端的单据类型校验拒收(报错)。稳妥的做法是单据类型拆策略,赠品一条、正单一条,各自独立调度。

坑 2:行项目被拍平成表头 赠品出库经常一行就完事,但接口响应里明细行仍然是数组。有些项目里工程师图省事直接取第一行,结果数量、单价全错,财务对账差了一行。正确做法是按 FEntity 数组逐行展开,行数和源端严格一致。

坑 3:目标端单据编号重复 幂等键用的是 order_no,但 ERP 端有时会因为格式或前缀冲突把这个编号判为已存在。常见应对是源端 idCheck=true 后,在中间层再加一层「目标端按 FBillNo 查询,存在则跳过」的逻辑,而不是无脑重推。

坑 4:库存方向字段被忽略 赠品出库在某些版本的 ERP 里,FStockDirect 不传会被默认填成"入库",直接导致账面方向反了。中间层一定要显式写 0(普通出库),不要依赖默认值。

坑 5:组织多版本下找不到对应组织 源端仓库编码 A,在 ERP 库存组织 106 下能查到,在 100 下查不到。中间层补默认组织时,要按当前生效的库存组织来写,而不是一次性写死。如果企业存在多库存组织,建议在 Qeasy 的映射表里维护「仓库 → 组织」的对应关系。

适用场景与不适用场景

适用:ToB 渠道赠品、促销活动赠品、样品出库、售后补发等"非销售正单但要走库存账"的场景;单据量从日均几十到几千都适用。

不适用:赠品金额为负、跨组织调拨、需走审批流的赠品申请,以及需要和正单做合并开票的场景——这些要么走专门的调拨策略,要么放在订单层而不是出库层处理。