退货入库单同步实战:从营销云到金蝶云星辰的全链路落地方案

这个策略解决什么问题

在零售与分销场景里,经销商把货退给品牌方是常态:门店撤柜、批次召回、客诉换货,都会在营销云里生成退货单。财务和供应链需要在 ERP 里同步生成红字入库单,才能完成库存冲回、成本核销和应收应付调整。这条链路看似只是一张单据的回写,实际上最常见的问题不是"能不能传",而是"传过去后编码对不对、日期准不准、库存冲得准不准"。我们用轻易云数据集成平台(Qeasy)承接这件事,把营销云的退货单据稳定地落到金蝶云星辰里,做到以单据号为锚点的可追溯。

数据流向与字段映射

整体流向:营销云(源,WebAPI 查询) → 轻易云中间层(映射、清洗、编码转换) → 金蝶云星辰(目标,WebAPI 写入)。

关键字段对照表:

业务含义	营销云(源)	中间层处理	金蝶云星辰(目标)
单据号	number	作为幂等主键写入备注	remark 追加 `来自营销云-{{number}}`
审核时间	auditTime	截取日期部分	bill_date(出库日期)
经销商/客户	extCusCode	通过 `_findCollection` 在客户集中查找 id	customer_id
收货地址	shippingAddress	原值透传	contact_address
来源标识	—	写死	bill_source = ISV

_findCollection 是轻易云常见的编码映射集中管理方式:把源系统的客户编码与目标系统的客户 id 维护在一个查找集合里,同步时按编码取 id,避免散落在每条记录里。

在轻易云上如何配置

源端配置要点:接口 /erp/api/order/query/saleReturnOrder,POST 查询,只拉已审核(status=1)的退货单,按更新时间窗口拉取:beginTime 使用变量 {{LAST_SYNC_TIME|datetime}},endTime 留空,系统自动填当前时间。idCheck 开启,保证幂等。

目标端配置要点:接口 /jdy/v2/scm/sal_in_bound,POST 执行类接口。customer_id 走查找集合;bill_date 用 {{auditTime|date}} 只取日期部分;remark 拼接源单单号,方便日后回溯。

平台级注意:源端 crontab 设为 */8 8-21 * * *,目标端 */7 7-23 * * *,两侧错峰分钟级调度,既能保证准实时,又不会在源端高峰期被并发拖垮。

实施步骤

我们把这个策略分三阶段上线。

阶段一:增量起点对齐。先在营销云手工审核一张退货单作为基准,轻易云里以这笔单据的审核时间作为 LAST_SYNC_TIME 起点,跑一次增量抓取,确认能把这一张推到金蝶云星辰,核对客户、日期、备注是否正确。

阶段二:全量触发与对账。把 beginTime 向前回拨到业务要求的起始日,补齐历史数据;同时在金蝶云星辰端按单据号逐单核对,确认库存红字与营销云退货数量一致。这里典型错误是用全量覆盖增量,导致 LAST_SYNC_TIME 被错位覆盖,后续漏单。

阶段三:调度频率与监控。上线后保留两侧错峰 cron,轻易云上对"查询无数据"、"目标接口 4xx/5xx"、"查找集合未命中"这三类异常分别配置告警;前两周每天做一次单据号抽样对账,稳定后改为每周。

踩坑复盘

日期格式错位。营销云返回的是带时间的字符串,直接传给金蝶的日期字段会校验失败。稳妥的做法是用 {{auditTime|date}} 这种模板变量把时间裁掉,只送 YYYY-MM-DD。
客户编码映射散落。早期我们把 _findCollection 写在每条记录的映射里,后来客户一变就漏改。集中管理的做法是把查找集合做成可维护的码表,源编码命中即取 id,未命中走告警而不是默认匹配。
幂等键选错。最初用行 id 做幂等,源端一旦重发整张单据就会重复入库。稳妥的做法是用单据号 number 作为幂等主键,落到目标的 remark 里,人工或回查都能定位。
crontab 没错峰。两侧调度都落在整点,目标端偶发 429。错峰 */8 与 */7 这种错位分钟在生产里非常有效,比加限流省事。
审核状态过滤遗漏。源端默认会拉出未审核单据,推到金蝶就成了"未生效的红字入库"。务必在请求里固定 status=1。

适用场景与不适用场景

适用:有营销云作为订单/退货入口、ERP 作为库存与财务底座的零售或分销企业,退货量在每天几百到几千单之间,需要近实时同步。不适用:跨法人主体、需要在多组织间拆单的复杂退货;以及退货需要审批流、且审批节点在 ERP 内的场景,这种建议先在 ERP 内建退货单,再做下游分发。