退货入库单同步实战:从营销云销售退货推金蝶云星辰的策略拆解

这个策略解决什么问题

某零售企业的营销云承担前端经销商退货申请,金蝶云星辰负责后端库存与财务核算。营销云审核通过的退货单需要及时落入星辰,生成销售入库单冲减库存并进入应收应付流程。一旦链路断了,门店退货无法入账、库存对不平、经销商结算也会被卡。我们用轻易云数据集成平台(Qeasy)承接这一段,把审核后的退货单按增量方式定时推到星辰。

数据流向与字段映射

数据从营销云出发,经过轻易云的中间层做映射与转换,落到金蝶云星辰的销货入库接口。源端是查询类接口,只拉已审核(status=1)的退货单;目标端是执行类写入接口。

关键字段对照:

行项目里物料编码同样要走映射,把营销云编码翻译成星辰物料 id,这是最容易出问题的环节,后面踩坑部分会展开。

在轻易云上如何配置

在轻易云集成平台里,这条策略按「源连接器 → 映射器 → 目标连接器」三段式配置。

源端选 WebAPI 查询模式,接口路径对应营销云的退货单查询,主键用 number,idCheck 打开以保证幂等;请求参数里 status 写死 1,beginTime 用内置变量 {{LAST_SYNC_TIME|datetime}},这样每次调度只取上次成功时间之后的增量,避免重复拉全量。

目标端同样是 WebAPI,但 effect 改为 EXECUTE,接口是星辰的销货入库。customer_id 不直接传编码,而是用轻易云的 _findCollection 写法,从已经同步到平台内部的客户档案集里按编号查到内部 id 再下发——这是轻易云客户里非常常见的「表头表体分阶段」应对模式:先把客户、物料基础资料同步进平台,退货单再用平台 id 下发,避免两套系统编码错位。

编码映射集中管理是另一个稳妥做法。我们在轻易云里维护一张物料映射表,源编码作为 key,星辰内部 id 作为 value,行项目写入前先查表,查不到就进异常队列,而不是粗暴地让接口报错。

实施步骤

整个上线分三个阶段:

第一阶段,增量起点。先确定 LAST_SYNC_TIME 的初值,通常选业务上线当天 0 点往前推几天,先把存量已审核退货单跑一次,确认映射和写入链路通畅。

第二阶段,全量触发。上线当日手动触发一次全量回灌,把历史退货单一次性同步进星辰。完成后立刻更新游标到当前时间,后续就只看增量。

第三阶段,调度频率。源端 cron 设为每 8 分钟一次(7-23 点执行,避开凌晨),目标端设为每 7 分钟一次。两个错开几分钟,既不会空跑也不会堵队列。如果营销云退货量不大,可以把源端放宽到 15 分钟一轮;但目标端建议保留较高频次,确保审核后尽快入账。

踩坑复盘

坑一:客户映射集没有提前建好。 上线当天才发现星辰里的客户档案还没同步进平台,所有 _findCollection 都返回空,退货单整批失败。稳妥的做法是:把「查询客户」「查询物料」这类基础资料同步策略(sequence A/B)放在退货单同步之前上线,并且设成强依赖,只有基础资料到位才允许推单。

坑二:auditTime 为空导致 bill_date 解析报错。 营销云偶尔会回传未填审核时间的脏数据,落到星辰侧就日期格式不对,整张单被退回。建议在映射器里加一道空值判断,为空的回退到 createTime,再不行就回退到当前日期并打日志告警。

坑三:beginTime 写成了创建时间而不是更新时间。 营销云接口里 timeType 控制按哪种时间查增量,默认是创建时间;如果业务上退货单是「审核后才算生效」,必须把更新时间纳入游标,否则审核延迟的单会被漏掉。我们在请求里把 timeType 显式置 1,并按更新时间取游标。

坑四:行项目数量或单位不一致,被星辰侧数量校验拦下。 营销云退货数量可能是销售单位,星辰入库要求库存单位;单位换算没做,单据就建不出来。映射阶段一定要做单位换算,查不到的单位进异常队列人工处理,不要静默丢弃。

坑五:幂等键没起作用,重跑产生重复单。 虽然我们用了 number 当幂等键,但如果中途失败重试,且目标接口本身不支持按外部单号查重,就会出现重复。我们靠轻易云的「按 number 去重 + 失败回滚」机制兜底,平台侧落库失败时不向目标接口下发,避免脏数据。

适用场景与不适用场景

适用:营销云做订单入口、星辰做库存/财务出口的零售或分销场景,退货量在每天几百到几万单之间,需要按增量、定时、幂等方式同步。不适用:需要实时秒级同步(应改用事件驱动)、退货流程需要审批流穿透到星辰、或者退货涉及跨组织调拨(需要更复杂的拆单逻辑)。

Conclusion

退货入库同步看似只是一个查询加一个写入,但里面藏着基础资料依赖、单位换算、幂等与游标四件套。把这几件事在轻易云里一次性搭好,后续从几十种单据同步策略(本次项目一共 66 条)扩展时,就能复用同一套映射与调度范式,少踩一次坑,就少一次返工。