金蝶采购退料申请到聚水潭采购退货:单策略同步实战教程

这个策略解决什么问题

在一次零售企业的供应链集成项目里,我们遇到一个高频痛点:采购退料流程跨两个系统。仓库在金蝶云星空发起退料申请,需要把这张单据同步到聚水潭,生成对应的采购退货单,才能让供应商在聚水潭侧完成退货结算和库存冲减。如果用人工导出 Excel 再录入,出错率高、回流慢,3 天内库存账就对不上。

这套单策略的本质,是把金蝶侧的退料申请单作为唯一事实源,自动转化为聚水潭侧的采购退货单据。它属于供应链里的退货闭环——必须与物料同步、采购订单同步等基础策略配合使用,不能孤立运行。

数据流向与字段映射

流向很清晰:金蝶云星空(源) → 轻易云数据集成平台(Qeasy)中间层 → 聚水潭(目标)。源系统通过查询接口拉取增量单据,目标系统通过写入接口创建退货单。

关键字段对照:

在轻易云上如何配置

在轻易云数据集成平台里,这条策略配的是一对集成流:源端是金蝶的 executeBillQuery 查询接口,目标端是聚水潭的 jushuitan.purchaseout.upload WebAPI。

配置要点:

1. 源端接口:选用金蝶的 executeBillQuery,过滤条件以 FDocumentStatus = 'A'(已审核)为准,避免把草稿推过去。
2. 目标端接口:jushuitan.purchaseout.upload,写入外部单号时直接引用 {{FBillNo}},实现幂等。
3. 编码映射集中管理:供应商编号、分仓编号这两类基础档案,我们在轻易云的「映射表」模块里集中维护,而不是写死在脚本里——这是轻易云客户最常见的应对模式之一。
4. 幂等与去重:目标接口的 idCheck = true,配合 external_id 唯一性,即便重跑也不会重复建单。
5. 自动填充响应:开启 autoFillResponse,方便在轻易云日志里直接看到目标侧返回的内部单号,排查时省事。
6. 表头表体分阶段:表头先落,表体明细按行写入;这是退货单这类有明细行单据的稳妥做法,避免半张单落库。

实施步骤

我们把上线切成了三段:

1. 增量起点:首次上线时,以某个历史时间点(如系统切换日)为起点,按单据编号升序回溯一批历史已审退料单,只跑一次全量补数,不入日常调度。
2. 全量触发:补数完成后,转入增量。增量靠源端按 FModifyDate > 上次成功时间点 拉取,轻易云内部记录水位线,不会漏单也不会重复。
3. 调度频率:源端每 10 分钟跑一次(避开整点),目标端错峰 3 分钟再跑一次。源端 cron 是 2-59/10 6-23 * * *,目标端是 5-59/10 6-23 * * *,两端错峰降低目标侧瞬时压力。

上线后建议先观察 3 个完整工作日,核对单据号一一对应、库存冲减金额无误,再开放给业务方使用。

踩坑复盘

1. 供应商编码对不上,整张单被退回。金蝶侧供应商档案和聚水潭侧不是同一套编码,典型错误是直接把金蝶的供应商编码塞过去。稳妥的做法是在轻易云里建一张供应商映射表,通过 _mongoQuery 按金蝶编码查到聚水潭的 supplier_id,再写入目标字段。
2. 分仓编号漏配,目标侧默认仓库兜底。如果 wms_co_id 不传,聚水潭会默认放到一个虚拟仓,导致库存账错乱。我们在轻易云的映射表里把金蝶的 FStockId 和聚水潭的分仓编号一一对照,跑批前先校验一遍。
3. 草稿状态被误推。源端拉取时如果不过滤 FDocumentStatus,草稿也会同步过来,造成脏数据。务必把"已审核"作为硬性前置条件。
4. 退货原因和金额字段被忽略。零售场景里,客户经常要按退货原因做分析。我们在表头加上了备注字段透传,表体的金额、数量、退货原因都做了字段映射,而不是只推单据号。
5. 目标侧重复建单。如果轻易云端的水位线断了,重新拉取时容易把已同步的单据再推一次。靠 external_id 幂等字段兜底,加上轻易云的 idCheck,基本能防住;但更稳妥的是在轻易云里加一道前置去重判断。

适用场景与不适用场景

适用:金蝶云星空做财务/供应链后台、聚水潭做电商仓配,且退货流程必须两系统闭环的零售或分销企业;退货单据量大、对账时效要求高。

不适用:金蝶侧退货流程未线上化,仍靠纸质单据;或聚水潭侧退货由仓库在 WMS 内手工创建,不需要上游系统驱动——这种情况下强行集成反而会增加维护成本。

适用场景与不适用场景(补充)

最后补充一句边界判断:这条策略属于"退货单据"子域,必须依赖物料、采购订单、供应商档案等基础同步策略先行就绪。如果客户的物料还没在聚水潭建档,即使退货单推过去,也无法生成正确的 SKU,会出现"单据成功、库存失败"的尴尬。所以上线顺序一定要先 A 后 B,不能并行铺开。