退货入库同步实战:营销云退货单到金蝶云星辰的端到端落地

这个策略解决什么问题

某零售企业的退货流程卡在两个系统之间:前端营销云里有经销商提交的退货单,后端金蝶云星辰需要尽快生成销售入库单以便冲销库存与应收。人工每天搬运既慢又漏,3 天后两边数量就开始对不齐。这个策略的目标只有一个——把营销云已审核的退货单,稳定、低延迟、可重跑地写进金蝶云星辰,中间不丢单、不重单。

数据流向与字段映射

数据流向非常线性:营销云(源)→ 轻易云中间层 → 金蝶云星辰(目标)。源端调用 POST /erp/api/order/query/saleReturnOrder,按 tenantId + status=1 + beginTime/endTime 增量拉取已审核退货单;目标端调用 POST /jdy/v2/scm/sal_in_bound 执行入库。

关键字段对照(精简后):

业务含义	营销云(源)	金蝶云星辰(目标)	处理方式
单据号	`number`	`id`(幂等键)	源号当目标幂等键
经销商/客户	`tenantId`	`customer_id`	通过 `_findCollection` 按外部编码查客户档案
单据日期	`auditTime`	`bill_date`	`{{auditTime
单据备注	`remark`	`remark`	拼接「来自营销云-{number}」便于追溯
联系信息	`shippingAddress`、`contactLinkman`	`contact_address`、`contact_linkman`	直接透传

表体走的是「表头表体分阶段」模式:先落表头拿到目标 id,再用明细行接口或嵌套数组把行项目带上,避免一次推送因某一行字段问题导致整张单废掉。

在轻易云上如何配置

我们用轻易云数据集成平台(Qeasy)承接。典型配置分四块:

源模型:WebAPI / QUERY,number 作为唯一键,idCheck 打开,自动回填响应。增量字段用 {{LAST_SYNC_TIME|datetime}} 绑定 beginTime,这样平台会替我们记住上一次跑成功的截止时刻。
目标模型:WebAPI / EXECUTE,bill_source 固定写 ISV,id 当幂等键。客户档案这种外部依赖,通过 _findCollection find id from {集合ID} where number={{extCusCode}} 在中间层完成编码映射——轻易云上把这种查找逻辑集中放在「映射表」里,后面退货单、订单、出库单共用同一张映射,新增经销商时不用每个策略都改。
转换脚本:做单位换算、税率兜底、空值替换;行项目数量、含税单价这种关键字段,显式判空,缺值就进「待人工补单」队列而不是直接入库。
调度:*/8 8-21 * * *,每 8 分钟一轮,覆盖白天营业时段;夜间做全量对账脚本,与白天增量并行——这是轻易云客户里常见的「增量与全量双轨」做法。

实施步骤

分三阶段上线,别一上来就全量跑:

阶段一·增量起点:选定一个历史时间点作为 LAST_SYNC_TIME 初值,例如当天 00:00。手动补跑当天 00:00 之前的所有「已审核」退货单,确保目标系统基线数据完整。
阶段二·全量触发:对历史未同步数据,单独跑一次全量补数脚本,带 idCheck,允许重跑。补完后再切换到增量调度。
阶段三·调度频率:营业时段 */8 8-21 * * * 拉取,夜间降低频率或停跑,只留全量对账。监控指标盯三件事:单据数环比、失败重试次数、customer_id 查不到的客户数。

踩坑复盘

customer_id 查不到就整张单失败:典型错误是把外部编码硬塞进 customer_id。稳妥做法是源端有就给,没有就走 _findCollection 查映射表;查不到时,整张单进异常队列,不要静默丢弃。
auditTime 时区漂移:营销云给的时间字符串带时区信息,直接用会在跨日后丢边界单。处理时统一按业务时区截断到日期,再传给 bill_date。
重跑导致重复入库:源端如果按时间窗拉取,「已审核」状态的单在窗口内被改价,重跑时会再写一次。稳妥做法是目标 idCheck=true,单据号作为幂等键,行项目层面再按 (单号+行号) 去重。
行项目里单位不一致:营销云按「箱」,金蝶按「盒」。不要在策略里写死换算,放到「映射表」里按 SKU 维护,后面订单同步、出库同步都能复用。
remark 字段被覆盖:直接把源端 remark 透传会把追溯信息冲掉。常见做法是拼接「{remark}-来自营销云-{number}」,既保留原备注,又留了溯源串。

适用场景与不适用场景

适用:前端业务系统产生已审核退货单、后端 ERP 需要实时生成销售入库单做库存与应收冲销,且单据体量在日均数千单以内的零售/分销场景。不适用:需要冲销到批次级、保质期级、或跨法人组织即时改写成本价的复杂制造场景;也不适用于退货单状态频繁回退(从已审核回到未审核)又要严格双向同步的场景——后者建议先加一层状态机中间表。