销售退货入库单同步实战：金蝶云星空 → 小蜜蜂WMS

这个策略解决什么问题

退货流程最容易卡在「单据到 WMS 那一刻」。客服在云星空里把退货审核通过，仓库却迟迟收不到指令；等用户电话打过来，WMS 操作员才知道有这单货要收。我们这次要聊的，就是把云星空的销售退货单按审核时间增量拉出来，转化成小蜜蜂 WMS 的入库订单（退货入库），让仓库和财务对得上一根线。

数据流向与字段映射

整体流向是：金蝶云星空（源，QUERY）→ 轻易云数据集成平台（中间层）→ 小蜜蜂 WMS（目标，EXECUTE）。

云星空侧通过 executeBillQuery 查询销售退货单，关键过滤字段是 FApproveDate（审核日期），单据号取 FBillNo，分录唯一标识取 FEntity_FENTRYID，开启 idCheck 做幂等。我们用到的请求字段大致如下：

表格只列关键字段，实际配置里还有备注、币价、批次等十几列，按需取即可。

在轻易云上如何配置

我们在客户现场用的是轻易云数据集成平台（Qeasy），策略配置分四块。

1. 源平台：选金蝶云星空，API 选 executeBillQuery，方法 POST。主键字段 FBillNo，分录主键 FEntity_FENTRYID，勾上 idCheck=true，开启 autoFillResponse 让平台自动展开返回结构。
2. 目标平台：选小蜜蜂 WMS，API 选入库订单 /inOrders/v4_1，方法 POST，主键 id，同样开幂等检查。
3. 字段映射：在「编码映射集中管理」里维护组织、客户、仓库的对照关系，避免在每个策略里重复写。这种「编码映射集中管理」是轻易云客户里用得最多的应对模式，物料新增、客户新增、退货入库等策略都共享同一张映射表。
4. 调度与过滤：源端 crontab 写 0-59/5 * * * *（每 5 分钟的 0 秒起跳），目标端错开 3 秒写 3-59/5 * * * *，避免两端同时拉取打挤。过滤条件用 FApproveDate >= 最近一次成功时间。

实施步骤

我们一般把一个策略的落地拆成三段：

• 第一步：增量起点。先用一次历史窗口（比如近 7 天）做冷启动，把存量退货单全部推过去；这一步用「全量触发」，跑完记录最大审核时间。
• 第二步：全量回灌。冷启动完成后，再单独触发一次全量，把漏掉的、之前审核状态变更的单据补齐；这一步会跟增量起点有重叠，但靠 idCheck 去重，不会产生重复入库。
• 第三步：调度频率切换。把源端 crontab 切到 5 分钟增量，目标端保持错峰执行；同时打开告警，连续两轮空跑或失败就发通知。

表头和分录建议分阶段上线：先跑通表头，确认 WMS 能收到入库订单；再放分录，把行项目物料、批次、数量补齐。这种「表头表体分阶段」的做法，能让排查时间从半天压到一小时内。

踩坑复盘

1. 审核日期不是业务日期。很多人第一次写过滤条件会顺手用 FDate，结果把跨月补审的单据漏掉了。稳妥的做法是用 FApproveDate 做增量键。
2. 货主编码硬编码翻车。shipperCode 直接写死在请求体里，换一家多货主客户就得改源码。客户里常见的应对是把它从映射表里读，作为变量注入。
3. 退货客户和源单客户混了。云星空退货单有 FRetcustId（退货客户）和 FCustId（原销售客户），推到 WMS 时一定要用前者，否则仓库联系错了人。
4. 幂等键选错导致重单。把 FBillNo 作为整单的幂等键没问题，但同一单如果分批推送行项目，行级就不能再用整单号，要带上 FEntity_FENTRYID。
5. 分录数量单位不一致。云星空分录里的基本单位和销售单位有时不同，WMS 入库按基本单位收；不做单位换算就会出现「数字对得上，件数对不上」。

适用场景与不适用场景

适用：销售退货单需要及时下推仓库、审核即触发、且对账要求日清的场景；尤其适合多货主、多组织、有退货考核的零售与分销企业。不适用：跨境退货需要先过海关的、需要在途状态多变的、以及退货后还要走返工再发货的复杂流程——这类建议拆成多个策略。