退货同步实战：聚水潭售后单到金蝶云·星空旗舰版退货单的策略落地

这个策略解决什么问题

电商仓库发出拒收退货后，售后单据需要在电商ERP和财务ERP之间闭环：库存冲销、应收冲减、开票依据都依赖这一张单据。手工二次录入既慢又容易踩错单据类型。本策略只做一件事——把上游电商ERP的售后单（拒收退货）按增量时间窗拉出来，转换成下游财务ERP的标准退货单写回。

数据流向与字段映射

数据流是单向的：上游电商ERP → 轻易云集成平台 → 下游财务ERP。中间层负责时间窗分页、编码映射、状态过滤和单据类型选择。

在轻易云上如何配置

第一步建源端连接器，API 选择 /open/refund/single/query，方法 POST，分页参数 page_index、page_size 写死 50，时间窗用平台内置变量 {{LAST_SYNC_TIME|datetime}} 和 {{CURRENT_TIME|datetime}}，状态过滤 status=WaitConfirm。第二步建目标端连接器，API 选 /kapi/v2/im/im_saloutbill/batchAddV2，方法 POST。第三步建映射策略，把表头字段一一对齐，行项目用轻易云的「行项透传」模式，避免手动拼 JSON。第四步挂调度：源端 05,35 8-22 * * *，目标端 20,50 * * * *，源在前、目标在后，留出处理时间。

编码映射集中放在轻易云的「映射表」里，店铺—客户编码、单据类型—组织编码都在一张表维护，客户新增门店不用改策略。

实施步骤

分三阶段跑：第一阶段全量触发，把历史待确认的售后单一次性同步，作为基线。第二阶段切增量，调度按源端时间窗自动滚动，{{LAST_SYNC_TIME}} 在每次成功跑批后落到持久化存储，断点重跑不会丢单。第三阶段是日常运行，源端半小时一抽，目标端每小时两次落库，留够缓冲。

上线前要做的三件事：把映射表里的店铺编码与客户编码核对一遍；在测试环境用真实拒收单跑一遍红字出库；准备一张幂等对照表，靠上游 as_id 做唯一键，回写失败重试时不重复落库。

踩坑复盘

踩坑一：时间窗边界重复拉。modified_begin 用闭区间、modified_end 用开区间看似稳妥，但服务器时钟有偏差，同一分钟内修改的订单会丢。稳妥做法是在中间层加 1 分钟重叠窗口，写入靠 as_id 幂等去重。

**踩坑二：单据类型选错。**拒收退货要走红字销售出库，不能用普通销售出库，否则库存冲销方向反了。这里容易翻车的是测试时用了普通出库看上去也对，等到月末结账才发现库存虚增。

**踩坑三：店铺—客户编码硬编码。**把映射写在策略脚本里，门店一调整就要发版。客户的常见应对模式是把所有映射抽到轻易云映射表，运行时查表，门店变更只改一张表。

**踩坑四：表头表体一次性提交。**行项目多的时候整批提交容易超时截断。分阶段更稳：先落表头拿到下游单号，再按行项目分批 batchAdd 追加明细，失败行重试不影响其他行。

踩坑五：拒收与正常退货混跑。type 字段不区分，拒收单和正常退货单走同一个策略，结果财务端看到的退货原因全是「拒收」。稳妥的做法是在源端加 type 条件分支，分别进不同映射，落到不同下游单据类型。

适用场景与不适用场景

适用于电商ERP与财务ERP一体化、需要按增量时间窗同步拒收退货单据、且下游用红字销售出库冲销库存与应收的场景。不适用于跨法人组织需要拆分应收的复杂集团、也不适用于需要实时秒级响应的客服退货改单场景——后者建议走消息队列加人工审核通道。