金蝶退料申请单到旺店通采购退货开单的同步策略实战教程

这个策略解决什么问题

在一次实际项目中，某零售企业的 IT 团队遇到一个典型问题：金蝶云星空里已经走完审批的退料申请单，需要在仓库端落到旺店通·企业奇门里生成采购退货开单，否则供应商对账和库存冲销都会滞后。看似只是两张单据的搬运，但单据状态、分录行项目、仓库与供应商编码一旦对不齐，3 个月后两边数字就会打架。我们在客户现场用轻易云数据集成平台（Qeasy）承接了这条策略，把金蝶退料申请单稳稳定时推到旺店通，形成闭环。

数据流向与字段映射

数据流向：金蝶云星空（源）→ 轻易云中间层 → 旺店通·企业奇门（目标）。

源端调用 executeBillQuery 拉取已审核的退料申请单，目标端调用 wdt.purchase.return.push 写入采购退货单。关键字段对照如下：

在轻易云上如何配置

在 Qeasy 控制台里，这条策略的配置要点有四块：

第一，源端数据源绑定金蝶云星空的 API 网关，选用 executeBillQuery，过滤条件勾上 FDocumentStatus = 'C'，这样源端就不会把暂存、创建、审核中的脏数据带过来。

第二，字段映射走可视化映射面板，编码类字段（仓库、供应商、物料）统一走轻易云的「编码映射」模块集中管理，不要散落在策略里。这是轻易云客户常见的应对模式之一：一旦新增仓库或更换供应商，改一处即可全策略生效。

第三，目标端写接口选 wdt.purchase.return.push，把源端分录字段映射到 detail_list 数组节点。表头和表体在轻易云里是分阶段处理的——先生成表头拿到目标单号，再批量下发表体行项目，最后回写关联关系。

第四，调度策略源端 cron 设为 */5 * * * *，目标端设为 */10 * * * *。源端频率略高于目标端，是为了保证下游有数据可消费且不会因源端瞬时拥塞而丢单。

实施步骤

上线前我们一般分三个阶段：

第一阶段：增量起点。在金蝶侧以一个明确的时间戳（比如 T-1 23:59:59）为增量起点，确保已审核单据按时间顺序进入中间层。这一步关键是确认金蝶的审计字段（修改时间/审核时间）准确。

第二阶段：全量触发。上线切换当天，手动触发一次历史全量回灌，让存量退料申请单补齐到旺店通。全量跑完后再切到增量。增量与全量双轨是轻易云客户常见的稳健做法。

第三阶段：调度频率与监控。源端 5 分钟一轮、目标端 10 分钟一轮，配合轻易云的运行监控面板观察积压、失败率、平均耗时。前两周建议每天人工抽检失败单据，第二个月后降为周检。

踩坑复盘

坑 1：单据状态不过滤。源端不勾 FDocumentStatus = 'C'，把暂存或审核中的单据推到下游，结果旺店通生成一堆作废退货单。这里容易翻车，稳妥的做法是在源端查询里就硬过滤状态。

坑 2：仓库编码一对多。金蝶一个组织下多个仓库共用相近编码，映射时没区分组织维度，导致入库仓和退货仓串了。典型错误是把编码当作全局唯一，实际必须按组织+编码组合。

坑 3：明细行丢失。直接用整段 JSON 推送，明细行被目标端忽略。稳妥的做法是在轻易云里显式声明 detail_list 为数组节点，并逐字段映射 FEntity_FEntryID 对应的货品、数量、批次等。

坑 4：幂等键缺失。不传 outer_no 或源端单号变更，重跑时目标端产生重复退货单。必须用 FBillNo 作为幂等键，并在 Qeasy 里开启幂等校验。

坑 5：采购单号引用开关。旺店通端有「采购退货开单必须引用采购单」配置，未开启时 purchase_no 留空无碍，一旦开启又没传值就会整单失败。上线前必须与业务确认开关状态。

适用场景与不适用场景

适用：源端单据状态机清晰（已审核后流转）、目标端有幂等键支持、编码档案已先于退货单完成同步的供应链场景。不适用：源端频繁反审修改、目标端无幂等保障、跨组织的退货冲销需要二次审批的场景。