聚水潭售后退仓单同步到金蝶云·星空退货单：轻易云实战教程

这个策略解决什么问题

某零售企业的售后链路里，聚水潭负责电商前端，金蝶云·星空旗舰版负责后端财务与库存。当抖音线下订单发生退货，仓库实际收货后，售后单要在两个系统里各登记一次——人工二次录入既慢又错。我们用轻易云数据集成平台承接，把聚水潭"销售退仓-实际收货"单据按时间窗拉取，直接生成金蝶侧的退货单，让库存与应收冲减有据可依。

数据流向与字段映射

整体流向：聚水潭（售后单查询）→ 轻易云中间层 → 金蝶云·星空旗舰版（退货单写入）。

源端接口为 /open/aftersale/received/query，POST 方式，分页拉取。关键入参：

• modified_begin / modified_end：增量时间窗，由轻易云调度自动填充上次同步时间到当前时间。
• date_type：本场景固定传 4（按修改时间）。
• page_index / page_size：分页参数，轻易云内一般给 1 和 50，循环翻页。
• shop_id：店铺编号，作为过滤条件传入。

源端返回里，io_id 既作为业务单号又作为幂等键，配合 idCheck=true 实现去重。

目标端接口为 /kapi/v2/.../im_saloutbill/batchAddV2，关键写入字段：

中间层承担三件事：分页聚合、时间窗推进、编码映射。

在轻易云上如何配置

第一步建源端数据源，选聚水潭适配器，填入应用密钥（不在文档里展开）；第二步建目标数据源，选金蝶云·星空旗舰版适配器，填好账套信息（脱敏略）。第三步建集成策略，把上面两个 JSON 元数据粘进去——轻易云会自动渲染请求/响应字段面板。

重点配置三处：

1. 增量水位：源端 modified_begin 用变量 {{LAST_SYNC_TIME|datetime}}，modified_end 用 {{CURRENT_TIME|datetime}}，轻易云每次调度自动推进。
2. 幂等控制：目标端开启 idCheck，主键取源端 io_id，重复请求直接跳过。
3. 编码映射：客户编码、组织编码、单据类型编码集中放在轻易云的"映射表"里维护，不要散落在脚本里——这是轻易云客户最常见的做法之一，后期加店铺或改组织只改一处。

实施步骤

我们在客户现场一般分三步走：

1. 全量初始化：把 modified_begin 临时改成固定历史起点，跑一次全量，确认金蝶侧退货单能正确生成、库存冲减无误。
2. 切换增量：全量通过后，恢复时间窗变量，跑 3–5 个调度周期（每 30 分钟一次），核对单据号是否连续、有无重复或漏单。
3. 常态调度：源端策略 cron 设为 05,35 * * * *，目标端策略设为 20,50 * * * *，错峰执行，给目标端留出写入与回写窗口。

回写检查建议每天做一次：抽样 5 单，对比两边金额、客户、仓库是否一致。

踩坑复盘

• 时间窗未推进：早期版本有人把 modified_begin 写死成常量，结果每次调度都拉同一批数据。稳妥的做法是确认轻易云调度日志里 LAST_SYNC_TIME 是否在递增。
• io_id 重复入库：聚水潭售后单存在改单重推场景，必须依赖 idCheck + 幂等键，不能只看单据状态。
• 客户编码找不到：店铺上线后忘了在轻易云映射表里补客户编码，目标端会整批失败。映射集中管理就是为这种场景准备的。
• 库存组织与销售组织混用：金蝶退货出库单里 org_number（库存组织）与 bizorg_number（销售组织）是两个字段，源端不直接给，配置时务必确认两个常量分别对应什么。
• 目标端限流：金蝶 batchAddV2 单次提交过大容易触发限流，建议轻易云端把单据按批次切分，每批 50 单以内。

适用场景与不适用场景

适用：电商退货收货后需要同步生成后端退货单、库存与应收冲减的连锁零售场景。不适用：纯线下退货无源单据、需要复杂审批流的售后工单，以及跨法人组织之间需要二次拆单的场景——这些要走专门的多组织分销策略，不能复用本方案。