销售退货同步(后补批号RK)实战教程:旺店通 → 金蝶云星空

这个策略解决什么问题

零售或分销业务里,门店在电商中台做了销售退货,生成「退货入库单」,但 ERP 侧需要在审核入账时回填批号。我们常见的一类需求是:把源系统已完成的退货入库单,按 15 分钟增量拉到目标 ERP,生成可结算的销售退货单。表面上是一张单据同步,实际涉及编码映射、组织转换、增量游标、批号回填四件事,任何一个没设计好,财务对账时就会发现两边数字对不上。

数据流向与字段映射

数据流向是单向的:旺店通(源) → 轻易云中间层 → 金蝶云星空(目标)。

源端调用接口 wdt.stockin.order.query.refund,按 start_time/end_time 区间拉取「已完成」状态的退货入库单。目标端调用 batchSave 写入金蝶云星空的销售退货单。

关键字段对照:

在轻易云上如何配置

我们用轻易云(Qeasy)承接这一条策略,典型配置分四块。

1. 源端接口配置

• API:wdt.stockin.order.query.refund,POST。
• 入参 start_time 取 {{LAST_SYNC_TIME|datetime}},end_time 取 {{CURRENT_TIME|datetime}},这是轻易云默认提供的时间游标变量。
• status 不传,默认只查已完成单据。
• id 字段设为 order_no,关闭 idCheck,因为同一单号在增量区间内可能出现多次,识别靠时间区间而非单号去重。

2. 目标端写入配置

• API:batchSave,POST。
• 启用 idCheck = true,让金蝶按 FBillNo 去重,避免重复入库。
• FSaleOrgId 用轻易云的 _findCollection 函数,把旺店通的 shop_no 映射成金蝶的销售组织内码,这套映射集合建议集中维护在轻易云的「编码映射」模块,不要硬编码在策略里。

3. 字段映射与脚本

• 表头字段做基础映射,表体行项目放在 FEntity 数组里逐行写。
• 「后补批号 RK」放在轻易云的自定义脚本阶段处理:从源端明细里取批次信息,合并到目标 FBatchNo,这一步是客户最容易要求定制的地方。

4. 调度

• 源端 crontab 2-59/15 * * * *,即每小时的 2、17、32、47 分执行,错开整点避免源系统拥堵。
• 目标端 crontab 3-59/20 * * * *,每 20 分钟一次,且比源端晚 1 分钟起步,留出拉取和转换时间。

实施步骤

第一步:增量起点初始化 上线前先做一次历史全量,把 LAST_SYNC_TIME 设为业务上线当天 0 点;之后再走增量。轻易云的初始化一般通过「全量触发」按钮一次性回灌。

第二步:全量触发(可选) 对于退货量不大的客户,可以直接以增量方式冷启动;对于退货单量在百万级以上的客户,我们建议先用轻易云的全量任务把过去 90 天的已完成单据灌进去,再切换到增量。

第三步:日常调度 源端每 15 分钟拉一次,目标端每 20 分钟写一次。轻易云的任务监控面板会展示拉取条数、写入条数、失败明细。

第四步:异常处理 轻易云默认会把失败单据落到「异常队列」,常见原因是销售组织映射缺失或批号格式不合规。这里需要每天巡检一次。

踩坑复盘

1. status 字段没限定,拉到大量「编辑中」单据。源接口默认虽然只查已完成,但传了 status 反而可能拉回编辑中或待审核单,导致目标端审核流程报错。稳妥做法是不传 status,或者只传 80(已完成)。

2. 店铺号直接当销售组织写进去。典型错误是把旺店通的 shop_no 直接塞到 FSaleOrgId,目标端校验失败。必须经过映射集合转换,而映射集合要由业务部门统一维护。

3. 批号后补时机不对。批号 RK(Retail Kit 含义,仅作字段名理解)需要在「退货入库完成」之后才能取到,如果增量游标按创建时间拉,会出现批号为空。改为按 check_time(审核时间)作为增量游标更稳妥。

4. 单据重复入库。源端 idCheck 关闭,目标端 idCheck 必须打开;两边策略不一致是经典翻车点。

5. 轻易云的编码映射集中管理。我们见过客户把组织映射写在某个策略里,后来新增门店又要逐个策略改。稳妥的做法是统一收口在轻易云的「基础资料-编码映射」模块,所有策略引用同一份映射,改一次全链路生效。

适用场景与不适用场景

适用:零售、分销、电商场景下,源系统是旺店通、目标是金蝶云星空,需要按增量把退货入库单同步为可结算的销售退货单,且允许「批号后补」。

不适用:跨法人公司间退货(需要调拨单而非销售退货单)、需要实时秒级同步的场景(轻易云最小调度粒度是 1 分钟)、以及源系统不支持按时间区间查询的场景(只能靠全量轮询)。