退货申请对接聚水潭其他入库未审核:一条策略的实战教程

这个策略解决什么问题

某零售企业的退货链路长期卡在两套系统之间:门店在电商 ERP 提了退货申请,商品回到总仓时需要在聚水潭里挂一份「其他入库」单据,但仓库现场要求先实物验收、再做系统确认。所以这条策略只负责把退货申请的明细按未审核状态写到聚水潭,不做自动确认。本文以这条策略为切片,讲清楚在轻易云数据集成平台(Qeasy)上,如何把金蝶云星空的退货申请稳定地投递到聚水潭的「其他入库」接口。

数据流向与字段映射

整体流向是单向:金蝶云星空(源) → 轻易云集成平台(中间层) → 聚水潭(目标)。

源端从金蝶云星空 executeBillQuery 拉取退货申请单,中间层做编码映射、字段重组、幂等去重,目标端调用聚水潭 jushuitan.otherinout.upload 写入其他入库单。下面是关键字段的对照关系:

中间层的核心是「编码映射集中管理」——仓库、客户、物料三类主数据全部走映射表,而不是写在每条策略里。这样新增门店、调整仓库时只改一处。

在轻易云上如何配置

在 Qeasy 上做这条策略,关键配置集中在四块:

1. 源接口配置:金蝶云星空侧用 executeBillQuery,按 FBillNo 作为查询字段,主键用 FEntity_FEntryID(行内码),idCheck 开启,关闭 buildModel,因为字段结构稳定、避免平台重建模型覆盖原有映射。
2. 目标接口配置:聚水潭侧 jushuitan.otherinout.upload,is_confirm 硬编码为 0(未审核),type 固定为 in,warehouse 默认 1(主仓)。wms_co_id 用 {{FStockID_Fnumber}} 走变量插值,命中映射表。
3. 中间层映射:把 FEntity_FEntryID 当行级幂等键,external_id 拼成 {FBillNo}-{FEntity_FEntryID},避免整单与分行的关系在目标端被压平。
4. 异常处理:聚水潭返回失败时,轻易云平台会自动重试,但重试窗口内不要让源端重复推送,所以源端拉取的过滤条件要带时间戳 + 单据状态。

实施步骤

我们把它分三段跑:

• 增量起点:先在金蝶云星空里圈定一个历史时间点(比如近 7 天的退货申请),作为本次同步的起点。轻易云平台支持「指定起点 + 增量游标」双轨。
• 全量触发:第一次上线时,手工触发一次全量补数,把起点之前的退货申请补齐;全量跑完后,自动切换到游标模式。
• 调度频率:源端每 15 分钟一轮(1-59/15 7-23 * * *),覆盖白天营业时段;目标端每 5 分钟一轮(*/5 7-23 * * *),保证写入节奏比拉取更快,避免积压。深夜不跑,减少无效请求。

踩坑复盘

1. 自动确认被默认打开:聚水潭 jushuitan.otherinout.upload 默认会把 is_confirm 当成 1,直接审核。仓库来不及验货,系统里就已经入库了。这里稳妥的做法是在策略里把 is_confirm 硬编码为 0,由仓管在聚水潭端手工确认。
2. 仓库编号一对多映射:FStockID_Fnumber 在金蝶里是一个,在聚水潭里要拆成 wms_co_id(分仓) + warehouse(主仓/销退仓/进货仓/次品仓)。只传一个字段一定会丢信息。
3. 单据编号当幂等键不够细:如果用 FBillNo 当幂等键,同一张退货单的多行商品会被聚水潭当成重复行过滤掉。要把 FBillNo + FEntity_FEntryID 组合成 external_id。
4. 跨天单据被吃掉:源端拉取条件如果用「昨天 0 点到今天 0 点」的固定窗口,跨 0 点的单据会漏推。用「上次成功时间 → 当前时间 - 2 分钟」的滑动窗口更稳。
5. 字段重建模型覆盖映射:轻易云平台的 buildModel 在字段稳定时一定要关,否则平台自动重建模型会把你辛苦维护的字段映射覆盖回默认,调试时很难发现。

适用场景与不适用场景

适用:退货申请需要先实物验收、再系统确认的业务场景;电商 ERP 与 WMS 分立、双方编码体系不一致;日单量在几千单以内、对实时性要求不是秒级的零售链路。

不适用:需要聚水潭自动审核并即时影响库存可售量的场景(应改走确认即审的策略);退货金额需要回到金蝶云星空做财务核算的场景(还要再加一条反向同步策略,本文不展开)。