聚水潭采购退货单同步到金蝶云星空：单一策略实战教程

这个策略解决什么问题

某零售企业的电商退货走聚水潭，财务与库存核算走金蝶云星空。退货一旦发生，仓库、应付、库存三个口径必须在同一时间反映出来，否则就会出现「电商说退了 100 件、ERP 里没单据、库存账还挂着正数」的尴尬。这条策略要做的就是：把聚水潭里的「采购退货单」按修改时间增量拉取，过滤到「已生效」状态，再按金蝶云星空的退料单模型写入。它不是数据仓库式的全量镜像，而是业务事件驱动的近实时同步。

数据流向与字段映射

整体链路是单向的：源 → 轻易云中间层 → 目标。

源端（聚水潭）调用的是采购退货查询接口，HTTP POST，分页参数固定每页 50 条；时间窗用 modified_begin 与 modified_end 控制，且「时间间隔不能超过七天」是接口层面的硬约束。状态字段只取 Confirmed（生效），其余状态一律不进下游。

中间层承担三件事：去重（按单号）、字段整形、把聚水潭的卖家编码翻译成金蝶云星空的供应商主键。这里用 _findCollection find supplier_code from ... where supplier_id={{seller_id}} 的写法，把映射表托管在轻易云里，便于后续维护。

目标端（金蝶云星空）调用 batchSave，单据类型固定为 TLD01_SYS，组织编码为 100。关键字段对照如下：

在轻易云上如何配置

在轻易云数据集成平台里，这条策略就是一个「源策略 + 目标策略」的组合。

源侧配置要点：API 选 /open/purchaseout/query，请求方法 POST，幂等字段 io_id 勾选「idCheck」，意为已写入的不再重复触发下游；时间窗变量用 {{LAST_SYNC_TIME|datetime}} 与 {{CURRENT_TIME|datetime}}，轻易云会按调度节奏自动滚动。

目标侧配置要点：API 选 batchSave，同样勾选 idCheck，并把「单据类型」与「退料组织」写成常量，避免每次调度都被业务变更带偏。供应商这类需要查找的字段，建议集中放在轻易云的「映射集合」里维护——这是轻易云客户最常见的应对模式之一：编码映射集中管理，一处改、处处生效。

如果退货单有「表头 + 表体」两层结构，推荐表头表体分阶段的写法：先落表头，确认成功后再逐行写表体，避免一行错就整单回滚。

实施步骤

第一步，先跑一次全量触发，把历史已生效的退货单补齐到金蝶云星空。这一步一般放在凌晨低峰期执行，人工触发即可，不必上定时。

第二步，确认全量数据无误后，把策略的 crontab 切到增量节奏。源端建议「每 10 分钟一次、覆盖业务时段」，例如 */10 1-2 * * * 这种窗口写法，把抓取压力集中在凌晨；目标端建议在业务白天运行，例如 3-59/10 8-22 * * *，错开源端的抓取峰。

第三步，观察三天。重点看：单据是否重复入库、供应商是否为空、库存数量与聚水潭口径是否一致。任何一项不一致，先停策略、再排查映射。

第四步，把监控告警挂上：连续两轮空跑、单据失败率超过阈值、时间窗漂移，都要触发提醒。

踩坑复盘

• 时间窗超过七天直接报错。聚水潭接口硬性规定 modified_begin 与 modified_end 间隔不能超过 7 天。我们第一次配时把窗口设成「近 30 天」，一上线就 400。稳妥的做法是轻易云侧用变量控制窗口长度，永远不超过 7 天边界。
• 状态字段不过滤，等于把草稿也写进了 ERP。如果忘记把 status 锁到 Confirmed，聚水潭里还没审核的退货也会被推到金蝶云星空，财务核销时直接对不上。典型错误是「先全量同步再说」，结果第一批数据里一半是废稿。
• 供应商不映射，单据直接保存失败。聚水潭的 seller_id 与金蝶云星空的 FSupplierID 不是同一套编码，不做映射就写入，会报「基础资料不存在」。
• 幂等键不勾选，重跑就重复入库。一旦调度重试或人工补跑，没勾 idCheck 就会产生重复退料单，库存被多扣。
• 表头与表体一起提交，一行错全单回滚。分阶段写入是更稳的做法。

适用场景与不适用场景

适用：电商采购退货需要近实时进入 ERP 进行应付与库存核算、源端与目标端编码体系不一致但有映射空间、接口支持按修改时间增量查询。不适用：退货需要复杂审批流后再入账（应改为状态变更触发）、源端接口不支持时间窗增量（只能走全量轮询，对账压力极大）、跨法人组织需要拆单的场景。