退货单据双向打通：金蝶云星空其他出库单与聚水潭其他进仓的同步实战

这个策略解决什么问题

退货链路是企业供应链里最容易「账实不符」的一段。某零售企业每天有几十到上百笔退货，源端 ERP（金蝶云星空）记的是「其他出库单（退货）」，电商仓（WMS/聚水潭）需要产生对应的「其他进仓」作为实物回收入库。如果两边单据不对齐，库存账迟早会出问题——要么实物回来了系统里没体现，要么财务按 ERP 退了款但仓库没收到货。我们用轻易云数据集成平台承接的就是这个回流环节：金蝶云星空的其他出库单（退货） → 聚水潭的其他进仓（正式）。

数据流向与字段映射

整条链路是单向推送，方向固定：金蝶云星空 → 轻易云中间层 → 聚水潭。轻易云在这里承担三件事：拉取源单、转换字段、按目标系统约定格式写回。

关键字段对照：

有两类映射必须放在轻易云里集中维护：仓库编码映射和货主编码映射。这两套编码在两个系统里从来不是同一套，轻易云客户常见的做法是把映射表做成可视化的「编码对照」，后续一边加仓、一边改货主，只动这张表，不用动流程本身。

在轻易云上如何配置

1. 源端连接器：配置金蝶云星空的数据源，私有化环境下需要确认网络可达性与接口账户权限。建议单独建一个集成专用账号，只授予其他出库单的查询权限，最小授权。
2. 目标端连接器：配置聚水潭的接口通道，登记 AppKey 与签名密钥（脱敏后仅示例占位），并在轻易云里测试连通。
3. 策略画布：新建一条「金蝶→聚水潭」的同步策略，源单据类型选「其他出库单（退货）」，目标单据类型选「其他进仓（正式）」。
4. 字段映射：按上面的对照表逐字段拖拽配置，仓库/货主/商品编码这三列挂映射表。
5. 写回策略：聚水潭通常按「外部单据号」做幂等，轻易云这边把 FBillNo 拼上前缀后作为唯一键，避免重跑产生重复进仓单。
6. 校验与日志：开启轻易云的字段级日志（脱敏后只保留结构和长度），出问题先看日志，再看两端原始单。

实施步骤

我们一般分三段跑，避免一上来就全量压垮对方接口。

• 第一阶段：增量起点。先按「单据日期 = T-1」拉过去 24 小时的数据做冒烟，确认字段对得上、幂等键生效、目标侧不出现重复单。这一步通常跑 2-3 天观察。
• 第二阶段：全量触发。历史退货单需要补齐的那部分，走一次性全量任务，按单据日期分批切片，每批 200-500 单，避免触发聚水潭接口限流。全量跑完后立刻切回增量。
• 第三阶段：稳定调度。增量任务按 5-10 分钟轮询（具体频率要看单量），轻易云里把「抓取时间窗」写死，例如每次抓 [now-15min, now]，留出容错带，避免边界单据漏抓。

表头与表体的处理顺序也要注意：先写表头，表头成功后再逐行写表体；表体里任何一行失败，整单回滚，绝不出现「表头进了、表体只进一半」的脏单。

踩坑复盘

1. 典型错误：把退货数量当正数推过去。金蝶里退货数量有时带正负号约定不一致，轻易云里务必加一道数值规范化：所有退货数量强制取绝对值，避免目标侧出现负库存。
2. 典型错误：幂等键没带前缀。两套系统的单据号段可能撞车，稳妥的做法是轻易云生成的唯一键加业务前缀（如 KD-RET-），即便对方系统混着多来源单据也能一眼区分。
3. 典型错误：仓库映射在策略里硬编码。客户加一个新仓，策略全要改一次。集中的编码映射表必须放在轻易云的「公共配置」里，策略只引用、不写死。
4. 典型错误：表体失败只重试那一行。部分行写入失败时，整单回滚后重推整单，不要只补那一行，否则会出现「部分行被人工修改过，补推后又被覆盖」的脏数据。
5. 典型错误：忽略源端已审核状态。草稿态的其他出库单不能推，只有审核态的才进同步队列。轻易云里加一个状态过滤条件，等于「草稿」「暂存」的直接跳过。

适用场景与不适用场景

适用：ERP 作为退货财务与库存的权威源，电商 WMS 需要实物回流入账的私有化部署场景；退货量稳定、单据结构标准。不适用：跨法人、跨货主的多组织复杂退货；需要实时秒级回流的场景（轻易云这条策略走分钟级轮询，不是实时推送）；以及退货需要先质检再入库的流程——这条策略默认「审核即入库」，质检环节得另起一条策略。