赠品销售退库单无关联集成方案实战教程

这个策略解决什么问题

赠品销售退库单"无关联"场景,指的是门店/电商侧发生赠品退货时,产生的退库单在源系统里没有挂接正价销售单据,只是孤立记录。财务和供应链需要在 ERP 侧如实入库并冲减成本,因此要把这类单据从源系统拉过来,写入目标系统。常见痛点是:单据类型要选"其他出库单"、货主和库存组织写死、赠品没有销售订单号可挂。我们在一次零售客户现场就遇到过:促销季赠品退货激增,仓库手工补单错乱,3 周后两边账面对不齐。下面是这一类策略在轻易云数据集成平台(Qeasy)上如何落地。

数据流向与字段映射

整体流向:源系统(退库单)→ 轻易云中间层(清洗、映射、校验)→ 目标系统(其他出库单)。

源端字段	含义	目标端字段	目标端取值/规则
order_no	退库单号	FBillNo	取 {{order_no}},作为单据编号
warehouse_no	仓库编号	FStockOrgId	通过仓库编码映射表翻译为组织编码
modified	修改时间	FDate	业务日期,格式 yyyy-MM-dd
status	单据状态	FBillNo 前缀/分支	仅同步已审核状态
—	单据类型	FBillTypeID	固定值 QTCKD01_SYS(其他出库单)
—	领用组织	FPickOrgId	固定值,由实施时确定
—	库存组织	FStockOrgId	与仓库映射后保持一致
—	货主类型	FOwnerTypeIdHead	固定值
明细行商品编码/数量	赠品行	FEntity 表体	按行写入

值得注意:源 API 是 wdt.wms.stockin.refund.querywithdetail(POST 分页查询),目标 API 是 batchSave(POST 批量保存),都是 POST 但语义不同——一个拉取、一个提交。

在轻易云上如何配置

在轻易云数据集成平台(Qeasy)里,我们按"一个源策略 + 一个目标策略 + 一条数据流"组织:

源策略:类型 QUERY,绑定 wdt.wms.stockin.refund.querywithdetail,开启 idCheck=true,以 order_no 作为幂等键。pager 与 params 走可视化参数面板配置,分页大小根据客户单据量调,通常 50–200。
目标策略:类型 EXECUTE,绑定 batchSave,单据编号、组织、货主、单据类型等写死在请求体里;动态值用 {{order_no}}、{{modified}} 这类变量引用。
数据流编排:中间层做 3 件事——状态过滤(只放行已审核)、仓库→组织映射、明细行拆装。映射表用轻易云的"集中映射管理"统一维护,避免散落在多个策略里。
表头表体分阶段:第一阶段只推表头+空表体跑通链路,第二阶段再放开明细行写入。这是我们给零售客户常用的应对模式,出问题容易回溯。
调度:源策略 crontab */15 * * * *,目标策略 crontab */20 * * * *,目标晚一拍落地,留出校验窗口。

实施步骤

阶段一:增量起点。先用 modified > 项目启动日 作为初始增量,跑 1–2 个周期,确认两边单据号能对得上。
阶段二:全量触发。放开时间窗,跑一次历史全量补数,目标端允许重复单据时务必打开幂等校验。
阶段三:稳态调度。源 15 分钟一轮拉取,目标 20 分钟一轮推送,轻易云平台会自动累积未处理数据,断点续跑无需手工介入。
阶段四:对账闭环。每天跑一次两端的单据号+金额对账,差异进入重推队列。

踩坑复盘

典型错误:单据类型选错。赠品退库本质是"入库冲回",但赠品没有销售订单关联,选成销售退货会被目标系统拒收。稳妥做法是统一用 QTCKD01_SYS(其他出库单)。
仓库编码 ≠ 组织编码。源端 warehouse_no 不能直接写到 FStockOrgId,一定要走映射表,否则组织隔离会失效。
幂等键只挂在表头。order_no 重复时目标系统可能提示成功但实际更新错乱,建议在轻易云里把幂等校验下沉到平台层,而不是依赖 ERP。
明细行漏写。赠品行可能没有标准价,目标端校验会卡住,需要在中间层补默认成本或者让实施顾问确认允许空价。
状态过滤做早不做晚。在源策略的 response 后置脚本里就过滤掉未审核单,不要等推到目标端再退,白白消耗配额。

适用场景与不适用场景

适用:赠品/促销品退货无销售单关联的零售、电商、连锁门店;需要把孤立的退库单据在 ERP 端建立成本冲减凭证。 不适用:赠品本身挂有正价销售单的(走 ToB 销售退货单策略);需要按批次/效期核算的场景(需在中间层补批次字段,本策略未覆盖);跨组织调拨退库(组织映射逻辑不同)。