采购退货单同步实战：金蝶云星辰到旺店通的对接方案

这个策略解决什么问题

采购退货单从 ERP 推到 WMS，听起来是一条简单的出库链路：单据审核后触发同步，目标系统自动审核并扣减库存。但在客户现场我们经常看到另一种画面——退货数量方向不对、仓库编码在明细里、供应商或物料在目标系统查不到……3 个月后两边数字对不上，财务和仓被迫对账到深夜。

这个策略要解决的核心问题只有一句话：让金蝶云星辰里已审核的采购退货单，干净、可追溯、增量地落到旺店通里，并自动审核扣减库存。我们在做某个零售供应链项目时，就是通过轻易云数据集成平台把这条链路打通，整个退货闭环从「靠人工导表」变成了「系统自然流转」。

数据流向与字段映射

整体链路非常清晰：金蝶云星辰 V2（源）→ 轻易云集成平台（中间层）→ 旺店通·企业奇门（目标）。源端用查询接口拉单，目标端用执行接口推单，中间层负责字段映射、状态过滤和主数据编码转换。

主表层面的核心映射是三件事：供应商 supplierid_number → provider_no、单据编码 bill_no → outer_no、明细数组 material_entity → detail_list。其中 warehouse_no 不像多数单据从主表取，而是从明细行里的 material_entity_stock_number 取，这是金蝶云星辰的数据结构特点。

明细行按行循环处理：仓库编码、规格编码、货品名称、单位、数量、含税/不含税单价、批次号、生产日期、有效期等字段一一对照。需要注意的是，退货数量 qty 在源端通常是负数（代表出库），同步前必须确认目标端是否需要做符号转换。

在轻易云上如何配置

在轻易云数据集成平台里，这条策略只需要配置一个集成方案，包含源端 QUERY、目标端 EXECUTE 和中间的映射关系。

源端配置要点：API 选 /jdy/v2/scm/pur_ret，类型 QUERY，方法 GET；分页参数 page=1、page_size=10；时间范围 start_bill_date={{LAST_SYNC_TIME|datetime}}、end_bill_date={{CURRENT_TIME|datetime}}；详情联查接口填 /jdy/v2/scm/pur_ret_detail，平台会自动按单据 id 拉明细。

目标端配置要点：API 选 wdt.purchase.return.push，类型 WebAPI EXECUTE，方法 POST；主键 outer_no 用源端 bill_no；明细节点 detail_list 直接绑定源端 material_entity，由平台按行循环。

映射层配置要点：这是最体现「工程师功底」的部分。我们通常会让客户采用「编码映射集中管理」的应对模式——把供应商、仓库、物料三类主数据编码对照放到独立的主数据策略里维护，退货单策略只引用，不重复定义。这样新增供应商或仓库时，只需在主数据侧补一条即可，退货链路自动复用。is_check 字段直接在目标端配常量 1 即可。

实施步骤

退货单同步建议按「全量打底 → 增量接管」的双轨思路落地。

第一步：全量触发。上线当天，先用「全量同步」把历史已审核的采购退货单一次性推过去。这一步的目的是把 outer_no 与旺店通单据的对照关系建立起来，后续增量就不会重复。全量跑完后，把调度切到增量模式。

第二步：增量起点。增量起点取「全量完成时刻往前回拨 1 小时」的 last_sync_time，避免边界单据漏单。这一步很关键——某制造企业第一次上线时，就是忘了回拨，结果有 3 张单据卡在边界时间点之后被漏掉，第二天仓发现库存对不上才发现。

第三步：调度频率。业务时段建议 */10 8-22 * * *，即每天 8 到 22 点每 10 分钟一次。退货不是高频业务，10 分钟足够；如果客户希望尽快看到库存扣减，可以压到 5 分钟，但没必要更高。非业务时段关掉调度，可以减少源端 API 压力。

第四步：上线观察期。上线后 3 天内建议盯三件事：单据数对得上、库存扣减方向正确、目标端自动审核无异常。常见的一个小坑是——旺店通以 outer_no 去重，重复推送会更新原单据，所以千万不要在增量逻辑里去掉 outer_no 校验。

踩坑复盘

1. 仓库编码取错位置。这条最常见。金蝶的仓库不在主表而在明细行，如果按主表取，会拿到空值或错值。稳妥的做法是确认源端数据结构，再决定从哪一层取。

2. 主数据没先行同步。供应商、物料、仓库如果在旺店通里不存在，退货单推过去会报「编码不存在」。我们见过某个项目因为物料主数据晚了一周上线，结果退货单整周都推失败。稳妥的做法是先跑主数据同步，再跑单据同步。

3. 数量方向搞反。金蝶退货数量为负，推到旺店通时如果不校验，会导致库存「越扣越多」。建议在映射层加一个符号处理逻辑，或者至少在测试阶段用单据验证。

4. 批次管理不一致。如果物料启用了批次管理，但某一方没传 batch_no、production_date、expire_date，会导致批次维度库存扣错。上线前必须确认两边批次管理开关一致。

5. 明细行映射漏字段。明细里有 tax_price、tax_amount、price、amount 四组价税字段，少传一组目标端可能直接拒收，或者金额对不上。建议把明细字段对照表打印出来，逐项打勾。

适用场景与不适用场景

适用：供应商退货流程以金蝶为审核中枢，旺店通为库存执行中枢的零售/分销企业；单据量中等、对账时效要求 30 分钟以内。

不适用：金蝶与旺店通同构部署且有官方对接通道的企业；退货流程需要先冲销采购入库再生成退货的复杂业务（这种通常需要采购入库单先落库，再触发退货）。