寄售调拨退回对接直接调拨(退货)同步方案

这个策略解决什么问题

在多组织、多库存形态的供应链环境里,某零售企业经常面临这样一个现实问题:业务前端发生的"寄售调拨退回"入库单,需要在后端 ERP 中按"直接调拨单(退货)"的语义重新表达,否则两边库存账和业务账长期对不上,审计时极易翻车。我们用轻易云数据集成平台(Qeasy)做这件事——把源端入库单按退货方向映射成目标端的直接调拨单,既保留业务轨迹,又让两边账目语义一致。

数据流向与字段映射

整体流向是单向的:源端(吉客云) → 轻易云中间层 → 目标端(金蝶云星空)。中间层承担编码映射、字段改写、单据类型转换三件事。

关键字段对照:

中间层的编码映射集中管理,是轻易云上常见的应对模式之一:所有仓库、组织、客户编码在统一映射表里维护,字段映射只在策略里引用,不写死。

在轻易云上如何配置

源端 API 选 WebAPI 的 POST 接口 erp.storage.goodsdocin.v2,作用为 QUERY,分页走 pageIndex/pageSize(默认 50 一页),增量时间窗用 {{LAST_SYNC_TIME|datetime}} 到 {{CURRENT_TIME|datetime}},单据号作为 idCheck 字段。

目标端 API 走 EXECUTE 类的 batchSave,POST 提交。关键点:

1. 单据类型 FBillTypeID:固定为 ZJDB01_SYS(标准直接调拨单),不要混用其他业务类型编码,否则目标端会拒收。
2. 调拨方向 FTransferDirect:写死 RETURN,对应"退货"语义。
3. 业务类型 FBizType:写死 CONSIGNMENT,与寄售场景对齐。
4. 调拨类型 FTransferBizType:固定 InnerOrgTransfer,这是目标端下拉列表里的标准值。
5. 组织字段 FSaleOrgId / FSettleOrgId:不直接写仓库编码,而是通过中间层映射表翻译成目标端的组织 ID,这一步建议放在轻易云的「字段映射」节点里集中维护。
6. 幂等:目标端 idCheck=true,源端单据号直接回写为目标端单据号,重复推送不会产生新单。

实施步骤

我们把它分成三个阶段推进,典型做法是"增量起点 + 全量触发 + 调度频率"双轨并行:

第一阶段:增量起点。上线前先用一次全量,把历史寄售退回单补齐;上线后切换到增量,以 {{LAST_SYNC_TIME}} 为水位线,每轮只拉新增或修改的入库单。源端调度 14 6-23 * * *,基本覆盖全天业务时段的小时级窗口。

第二阶段:全量触发。在月初、季度初等关键节点,人工或脚本触发一次全量回灌,核对两边库存账。这一步在轻易云上可以直接复用同一个策略,只改时间窗即可。

第三阶段:调度频率。目标端调度 47 * * * *,做成小时级,但把分钟错开(源端 14 分、目标端 47 分),避免两端在同一时刻互相等待。注意源端拉数据用小时窗,目标端写入也用小时窗,中间留出足够的转换与缓冲时间。

踩坑复盘

几次客户现场下来,我们总结出几条高频问题:

1. 单据类型选错。ZJDB01_SYS 到 ZJDB06_SYS 看上去只是编码差异,但目标端校验严格,混用会导致整批被拒。稳妥的做法是在策略里把 FBillTypeID 作为常量单独维护,不要混在字段映射里。
2. 组织编码直写仓库编码。源端的"仓库"和目标端的"组织"不是同一个语义,直接传值两边对不上。这是编码映射必须集中管理的原因——轻易云客户常见做法是把映射表放在中间层,字段映射只引用键值。
3. 增量起点没设好。第一次上线时 {{LAST_SYNC_TIME}} 没值,要么拉空,要么拉全量。建议先跑一次历史回灌,把水位线落到一个明确的时间点。
4. 幂等键丢失。目标端 batchSave 的幂等靠 idCheck,源端单据号必须稳定回写;若在中间层被改写过,会导致重复单。
5. 小时窗两端同时拉取。源端和目标端调度如果撞在同一分钟,目标端会拿到尚未完成转换的数据。把分钟错开是稳妥的做法。

适用场景与不适用场景

适用于源端使用吉客云、目标端使用金蝶云星空、且组织间存在寄售调拨退回业务的私有化部署场景,适合库存账需要按"直接调拨单(退货)"语义对齐的企业。不适用于非寄售场景(标准采购退货、销退等)、不适用于需要双向同步的场景、也不适用于源端无 goodsdocNo 幂等字段的轻量接入。