旺店通采购退货出库单到金蝶云星空采购退料单:单一策略同步方案实战
这个策略解决什么问题(场景与价值)
在一次零售供应链集成项目中,客户现场每天会从 WMS 侧产生几十到几百张采购退货出库单。仓内退货、供应商拒收、批次质量问题,都需要把退货事实回流到 ERP,生成对应的采购退料单,用于冲减采购入库成本、刷新供应商应付并更新库存账面。如果两边单据对不上,财务月底对账时就会卡壳。我们用轻易云数据集成平台(Qeasy)只做一条策略,把退货出库单稳定推到 ERP 这一侧的单据生成入口,价值就是把"退货事实"统一沉淀到 ERP 一处。
数据流向与字段映射(源 → 中间层 → 目标)
数据从 WMS 出发,进入轻易云中间层做清洗与映射,再写入金蝶云星空。WMS 侧调用的是采购退货出库单查询接口(带明细),金蝶侧用 batchSave 这种批量执行入口落地为采购退料单。
下面是一组关键的字段对照,编码和组织字段强烈建议在轻易云上集中管理,不要散落在每个字段的转换表达式里:
| 业务含义 | WMS 侧源字段 | 中间层处理 | 金蝶侧目标字段 | 备注 |
|---|---|---|---|---|
| 单据编号 | return_no | 直接透传 | FBillNo | 同一单据号贯穿两端 |
| 退料日期 | check_time(毫秒) | FROM_UNIXTIME(ts/1000, '%Y-%m-%d %H:%i:%s') | FDate | 时间戳转可读日期 |
| 退料组织 | return_no | _findCollection 反查采购退料单已有 FBillNo | FStockOrgId | 需有可查询的组织映射集合 |
| 采购组织 | 同上 | 同上反查 | FPurchaseOrgId | 与退料组织区分 |
| 结算组织 | 同上 | 同上反查 | FSettleOrgId | 建议与采购组织对齐 |
| 结算方式 | 源端未直接给出 | 由采购订单或供应商档案带出 | FSETTLETYPEID | 提前在编码映射里维护 |
在轻易云上如何配置
在轻易云数据集成平台里,这条策略的源是 WebAPI(查询类),目标是 EXECUTE(写入类),配置要点有四个:
第一,源端 metadata.api 用 wdt.purchase.purchasereturn.querywithdetail,开启 idCheck 与 buildModel,把退货单号 return_no 当作幂等键,单据拉回来时按单号去重,避免重复抓取。
第二,目标端走 batchSave,把组织类字段统一交给"编码映射"组件来解析——这是轻易云客户常见的应对模式:编码映射集中管理。我们把退料组织、采购组织、结算组织、结算方式放在同一张映射表里维护,策略里只引用,不在表达式里硬编码。
第三,明细行(表体)单独建一张子表映射,物料编码、数量、批次、仓库这些字段放在子表里分阶段落地。第一阶段先把表头写进去,第二阶段再补明细,是表头表体分阶段的典型做法。这样 ERP 端不会出现"有头无身"的脏单据。
第四,autoFillResponse 打开,让平台把返回字段自动回填到上下文,方便后续用 return_no 反查组织和供应商,避免每个字段重复写一遍 _findCollection。
实施步骤
一次实际项目里,我们把这条策略拆成三段跑:
第一段:增量起点。先用"最近一次成功时间 + 单据状态"作为增量起点,把历史未同步的退货出库单做一次补跑。增量起点不能直接拿系统上线当天,否则前几天的退货数据会漏。
第二段:全量触发。补跑完成后,再用一次手动触发的全量回灌,确保源端在窗口期内漏抓的数据也能进入目标端。轻易云里直接复制策略、把增量条件去掉即可,不要在原策略上"边跑边改",这是稳妥的做法。
第三段:调度频率。源端 crontab 设在每小时的第 50 分钟,目标端设在每小时的第 59 分钟,前后留 10 分钟做中间层落库与字段加工。营业时间窗口(如 7-22 点)覆盖即可,深夜无需跑。形成"增量与全量双轨"的运行节奏:日常增量 + 月度全量校验。
踩坑复盘
这里列几条我们在客户现场真实遇到的坑:
- 组织字段硬编码散落在表达式里。典型错误是每个字段都写一遍
_findCollection,结果某天 ERP 端组织调整,二十几个表达式一起失效。稳妥的做法是把组织、结算方式、供应商编码统一进"编码映射"组件集中管理。 - 表头先于明细落库,导致金蝶端脏单。有些团队图省事把表头表体放在一次
batchSave里,遇到明细行数量大或某行字段缺失时,会出现只有表头的单据。我们采用表头表体分阶段:先生成表头,再补明细,失败可重试且不会污染目标端。 - 时间戳未做时区与精度处理。WMS 给的
check_time是毫秒级 Unix 时间戳,直接写进金蝶日期字段会被拒。必须在中间层用FROM_UNIXTIME转换,并确认金蝶侧要求的时间精度(带不带时分秒)。 - 重复抓取导致金蝶端重复单。如果
idCheck没开、或者源端接口不支持按return_no精确去重,就会出现同一张退货单被多次推送到金蝶。每次推送前用单据号做幂等校验,是基本动作。 - 退货单对应的采购订单关联缺失。金蝶生成采购退料单往往需要回溯到原始采购订单的组织与结算方式。我们提前在编码映射里维护"退货单 → 采购订单 → 组织/结算方式"的链路,而不是在表达式里临时拼,避免运行时查不到。
适用场景与不适用场景
适用:WMS 端退货出库单与 ERP 端采购退料单一一对应,单据号可贯穿两端,组织与供应商编码可在轻易云编码映射中集中维护的私有化供应链场景。不适用:退货流程涉及多级审批、需要人工干预冲减金额,或两端组织/供应商体系差异巨大、无法用编码映射收敛的场景。