退货入库单据同步策略实战：从营销云到金蝶云星辰

这个策略解决什么问题

某零售企业用营销云承接经销商退货申报，财务侧需要在金蝶云星辰生成红字入库单。手工录入易出错、易出错、易出错——退货单据量大、品规多，编码一错就影响库存账。我们用轻易云做中间层，把营销云已审核的退货单按增量拉到中间层，转换后写入目标系统的销售入库接口，实现单据一处发起、两端一致。

数据流向与字段映射

整体链路是「营销云（QUERY）→ 轻易云中间层 → 金蝶云星辰（EXECUTE）」。源端是营销云的销售退货单查询接口，分页拉取已审核(status=1)的退货单；目标端是金蝶云星辰 V2 的销售入库接口。中间层承担清洗、编码转换与幂等去重。

关键字段对照：

业务含义	营销云字段	中间层处理	金蝶云星辰字段
来源标识	—	固定写入	bill_source = ISV
单据日期	auditTime	格式化为日期	bill_date
客户	extCusCode	_findCollection 按编码查客户 id	customer_id
备注	remark	拼接「来自营销云-单号」	remark
收货地址	shippingAddress	原值透传	contact_address
商品明细	entries[]	编码映射 + 行项目展开	分录明细数组
单据号	number	作为幂等键	写入备注便于核对

在轻易云上如何配置

源端策略选择 WebAPI/QUERY，用 POST 调营销云的退货单查询接口。增量字段用 {{LAST_SYNC_TIME|datetime}} 绑定开始时间，状态条件固定传 1（已审核/已出库）——这里有个细节，状态传 0 会把未审核单也拉进来，目标端会拒收。

目标端策略选 WebAPI/EXECUTE，调金蝶的销售入库接口。客户字段用 _findCollection find id from <客户策略> where number={{extCusCode}} 反查——这一步依赖基础资料同步先跑通。我们的常见做法是把编码映射放轻易云的客户、物料策略里集中维护（编码映射集中管理），退货策略本身只引用映射结果。

幂等靠两件事：源端 idCheck=true 防漏取，number 作为幂等键落到备注和后续对账。

实施步骤

第一阶段：铺基础资料。 先把客户、物料同步策略跑稳，确保退货单里的 extCusCode、商品编码能在金蝶侧查到 id。一般 sequence A、B 的基础策略先于业务单据调度。

第二阶段：增量起点。 第一次全量拉取用历史时间窗口初始化 LAST_SYNC_TIME，避免把几年前的老单全跑一遍。客户现场我们通常建议先以「近 90 天已审核单」做冷启动，再切增量。

第三阶段：常态调度。 源端设 */8 7-23 * * *（白天每 8 分钟一次），目标端 */7 7-23 * * *（每 7 分钟一次）。两边错峰 1 分钟，给目标端留处理窗口。白天高频、夜里低频，覆盖经销商集中退货时段。

第四阶段：对账与重放。 轻易云提供运行日志，按单号筛选失败记录，常见失败是「客户不存在」「商品编码未映射」，查基础资料策略补齐后单条重发。

踩坑复盘

状态位选错。 营销云 status 传 0 时会把草稿单也拉过来，目标端入库校验直接拒收——典型翻车点。稳妥的做法是源端固定传 1，并加白名单过滤异常状态。
编码映射散落在多个策略里。 退货单里出现的客户、商品编码如果在客户/物料策略里没建映射，会整批失败。我们的做法是所有编码映射集中放基础资料策略里维护（编码映射集中管理），业务策略只引用。
增量起点没设计。 直接用全量回溯会把三年老单一次性全推过去，目标端性能吃紧还容易触发限流。建议显式设定增量起点，先小窗口验证再放宽。
表头和表体一起推，没分阶段。 退货单明细行数多、和表头一起塞进同一个请求容易超时。我们的做法是表头先落、表体分批提交（表头表体分阶段），失败定位也更快。
幂等键设计薄弱。 仅靠单据号做幂等，如果源端重发时单号变化就会重复入库。建议把源端 id + number 组合作为幂等键落到备注里，便于事后追溯。

适用场景与不适用场景

适用：营销云单据状态稳定、需要准实时同步到金蝶做财务入库的退货业务；单据量白天集中、夜里稀疏。

不适用：源端单据状态频繁变更、需要回溯修订历史单据的场景；目标端是按月批次入账、不需要分钟级响应的财务场景——这时候定时批量导入更划算。