销售退货单同步实战：从旺店通到金蝶云星空的单一策略落地

这个策略解决什么问题

ToB 业务里，销售退货单从线上回流到 ERP，是供应链集成最容易被低估的一环。一次实际项目中，某零售企业最初只做了销售出库同步，售后退货完全靠人工在两边各录一遍，三个月后两边账对不上才发现：旺店通里 120 多张退货单，金蝶云星空只进了 60 多张。问题就出在「销售退货单查询」这条独立策略没人管。

这条策略的价值很朴素：让旺店通的退货入库单按既定节奏（素材里是每小时第 24、54 分）抓回来，落到金蝶云星空，形成可追溯的退货档案。自动化的核心不是省人力，而是让两边的单据号、日期、仓库、店铺代码一一对得上。

数据流向与字段映射

整条链路是单向 A_TO_B：源系统（旺店通·旗舰奇门）→ 轻易云数据集成平台作为中间调度层 → 目标系统（金蝶云星空）。

源端调用的是查询类接口 wdt.wms.stockin.refund.querywithdetail，POST 方法，幂等键取 order_no（入库单号），分页参数与业务参数都封装在一个 params 对象里往外送。目标端写入用的是批量保存接口 batchSave，同样 POST，单据号 FBillNo 作为主键 id，开启 idCheck 防止重复落库。

关键字段对照表（脱敏后）：

源端字段（旺店通）	目标端字段（金蝶云星空）	说明
`order_no`	`FBillNo`	入库单号，作为幂等键
`check_time`	`FDate`	审核日期，模板里用 `{{check_time\|dateTime}}` 做格式转换
`warehouse_no`	`Fwarehouse_no`	仓库编号
`shop_no`	`Fshop_no`	店铺代码
`details_list`（明细行）	`FEntity`（单据体数组）	行项目按数组展开
`status`	（由后端语义映射）	单据状态不在表头直传，靠业务规则判断

在轻易云上如何配置

在轻易云数据集成平台里，这条策略通常落在「集成策略」节点下，命名按业务模块归档，便于后期检索。几个典型配置要点：

第一，编码映射集中管理。仓库、店铺、客户这些主数据，轻易云客户常见的做法是单独维护一张映射表（甚至直接接一个主数据同步策略），不要在每个策略里硬编码。销售退货单里的 Fwarehouse_no 必须先经过映射，否则源端的内部编号到了金蝶云星空对不上仓库档案。

第二，表头表体分阶段处理。表头先按 order_no 去重入库，遇到目标端已存在就跳过；表体 FEntity 通过 details_list 数组展开，逐行写入。轻易云平台里的「表头表体分阶段」模式在退货场景里几乎是标配，因为退货经常会出现「先退头、后补明细」的二段式操作。

第三，请求参数和响应映射分开配置。源端的 request 里只放 pager 与 params 两个壳；目标端的 request 里通过模板变量 {{order_no}}、{{check_time|dateTime}}、{{details_list}} 把响应字段「喂」进来。autoFillResponse=true 会让响应字段自动暴露给下游映射，调试期很省事。

第四，crontab 慎改。源端默认 24,54 * * * *（每小时两抓），目标端写 1 1 1 1 1 看似禁用，实则是轻易云常用的「手动触发占位」写法，生产里靠上游事件或人工触发，不要误改成高频。

实施步骤

第一步：确认增量起点。 在轻易云里给 order_no 设置起点游标，建议从最近一次人工对账日期往前推 7 天，留出缓冲窗口。这一步典型错误是直接把起点设成「全量」，结果第一次跑就把历史几年的退货单全推下去，目标端要么报错要么数据膨胀。

第二步：全量触发一次性跑。 仅在项目上线初期或账实差异很大时执行一次，跑完后立即归档日志，确认单据数两边一致，再切到日常调度。

第三步：日常调度采用「增量 + 定时」双轨。增量靠源端时间戳驱动，定时按源端 crontab 每小时两抓。轻易云客户里常见的稳健做法是：定时跑兜底，增量跑提速，两条路径用同一张去重表。

第四步：异常单据隔离区。映射失败、必填校验不过的单据进入隔离队列，不要让一条脏数据卡住整批。

踩坑复盘

idCheck 没开就上线。 源端同号单据重复抓回来，目标端出现 N 条重复退货档案。稳妥的做法是 idCheck=true 配合 id 字段绑定 FBillNo，任何写入前先按主键查重。
日期格式没做模板转换。 源端 check_time 可能是时间戳或字符串，目标端金蝶云星空要求标准 datetime。素材里用了 {{check_time|dateTime}}，看似一行，删掉就翻车。
仓库/店铺编号裸传。 源端的内部编号和金蝶云星空的档案编号是两套体系，不经过映射直接 {{warehouse_no}} 传过去，目标端大概率报「仓库不存在」。
单据体数组忘了展开。 details_list 是数组，必须在模板里整体替换 {{details_list}}，不要在循环外取首元素，否则退货多明细只落了第一行。
crontab 误改成高频。 源端 24、54 分是有讲究的，避开整点峰值的抓取压力。一旦改成 * * * * *，源系统会因查询过频触发限流。

适用场景与不适用场景

适用：ToB 业务里退货节奏稳定、单据结构清晰、有明确幂等键（订单号、入库单号）的中小规模零售或分销企业；以及上线初期需要快速建立退货台账的项目。

不适用：退货需要跨多组织、多账套协同的集团型企业（建议拆策略）；源端接口频繁变动或字段语义不稳定的系统（应先做接口治理再做同步）；退货与冲销、成本核算强耦合的场景（这条策略只解决单据落库，不替代财务核算逻辑）。