聚水潭售后单到金蝶退货单同步实战：从增量拉取到目标单据落库的全流程拆解

这个策略解决什么问题

某零售企业在京东渠道的售后退仓单需要在 ERP 里及时形成退货单据，以便财务对账和库存回冲。聚水潭记录了「实际收货」状态的售后单，金蝶云·星空旗舰版要落地标准的销售退货单。这条策略就是把这二者串起来，让前端平台单据变更在 ERP 内闭环。

整体流向是「聚水潭 → 中间层（轻易云） → 金蝶云·星空旗舰版」，单向写入。

源端（聚水潭）拉取 /open/aftersale/received/query，按 modified_begin 到 modified_end 区间分页拉取，每页 50 条；主键是 io_id，辅以 idCheck=true 防止重复。

目标端（金蝶云·星空旗舰版）调用 /kapi/v2/im/im_saloutbill/batchAddV2 批量新增销售出库退货单，单据类型编码为 im_SalOutBill_STD_BT_S_R。

业务含义	聚水潭侧字段	金蝶侧字段	处理说明
单据号	`io_id`	`billno`	直接取原单号，便于跨系统对账
店铺/客户	`shop_id`	`customer_number`	走轻易云编码映射集中管理，避免硬编码
库存组织	固定值 `100`	`org_number`	私有化环境按实际账套调整
结算币别	固定 `CNY`	`settlecurrency_number`	跨币别时需另开策略
单据类型	隐含	`billtype_number`	锁定为退货标准单
业务组织	平台传值	`bizorg_number`	走映射表

注意：聚水潭的 shop_id 不能直接当客户编码，必须在中间层做一次店铺—客户映射。我们用轻易云的「编码映射集中管理」把店铺档案维护成一张可热更新的映射表，新接入渠道时改一处即可。

源端集成：选聚水潭适配器，配置 modified_begin 引用变量 {{LAST_SYNC_TIME|datetime}}，modified_end 引用 {{CURRENT_TIME|datetime}}，首次运行用兜底时间戳。
请求参数：把 page_index 设为 1，page_size 设为 50，date_type 取 4（按修改时间过滤）。
中间层转换：在轻易云数据集成平台里配置字段映射和「表头—表体分阶段」处理——先落表头（单据号、客户、组织），再循环表体行项目，确保行项目分摊一致。
目标端写入：调金蝶批量新增接口，开启 idCheck，失败行走错误队列。
变量管理：LAST_SYNC_TIME 和 CURRENT_TIME 由平台自动维护，回写策略运行完成后才推进游标，避免漏单。

我们建议分三阶段上线，避开一次性切换带来的风险：

阶段一：增量起点标定。手工对齐一批历史已收货单据作为基线，把 LAST_SYNC_TIME 初始化到「切换日前 7 天」，全量回灌后切换到增量模式。
阶段二：全量触发 + 增量并行。前两周同时跑全量和增量双轨，用轻易云的对比报表核对两边单据号是否一致，发现差异立即停增量。
阶段三：调度固化。聚水潭源端 crontab 设为 05,35 * * * *（每小时第 5、第 35 分钟触发），目标端写库 crontab 设为 20,50 * * * *，二者错峰 15 分钟，留出中间层转换和异常重试的窗口。

modified_begin 不要带时分秒截断。典型错误是用 00:00:00 做起点，结果凌晨改的当天单被漏掉。稳妥的做法是直接用上一次成功的 CURRENT_TIME，由平台毫秒级推进。
shop_id ≠ 客户编码。直接把店铺 ID 写到金蝶客户字段，运行两周后会冒出几百个「幽灵客户」。必须配置映射表，新店铺接入当天就要补全映射。
批量接口的单据号冲突。金蝶侧如果单据号手工录过同号，批量新增会整批失败。务必开启 idCheck，并把 billno 设为聚水潭原值，再让金蝶按其内部规则做唯一性校验。
表体行项目被截断。源端单据有 200 行明细，目标端一次批量 50 行，循环写入时若未用「表头—表体分阶段」，会出现表头写了但表体缺失的孤儿单。
私有化环境的时钟漂移。源端服务器与中间层时钟不同步，会导致 LAST_SYNC_TIME 推进异常。建议在轻易云里开启「NTP 漂移监测」，超过 30 秒告警。

适用：渠道平台单据进入「实际收货」状态后需要在 ERP 内形成退货单据的场景，尤其是多店铺、多渠道、有清晰「已收货」节点的业务。

不适用：跨境多币别、需要复杂审批流的退货场景；以及源端未提供修改时间增量字段、只能整库全量拉取的老接口。