退货入库单同步实战:从营销云到金蝶云星辰的单策略落地教程

这个策略解决什么问题

退货单据跨系统同步,是供应链集成里最容易被低估的一环。某零售企业的退货流程跑在营销云上,而财务与库存入账在金蝶云星辰里,如果两边不实时打通,就会出现「营销云里已经审核出库的退货,星辰里库存迟迟不见回流」,财务对账慢、仓库账面虚高,业务部门每周都要拉数对一遍。本文围绕单一策略——「退货入库单同步」,讲清楚怎么用轻易云数据集成平台(Qeasy)把它稳稳落地。

数据流向与字段映射

整体流向是:营销云(源)→ 轻易云中间层 → 金蝶云星辰(目标)。源系统通过 POST /erp/api/order/query/saleReturnOrder 按时间窗口拉取已审核(status=1)的退货单,目标系统通过 POST /jdy/v2/scm/sal_in_bound 写入销售入库单。

关键字段对照(节选自策略配置):

特别注意源端拉数接口的几个传参:tenantId 是经销商标识,每个租户单独配置;status=1 保证只取已审核单据;beginTime 用 {{LAST_SYNC_TIME\|datetime}} 实现增量,这是整套调度能跑起来的关键。

在轻易云上如何配置

在轻易云里,这条策略对应一个集成流,典型配置要点如下:

1. 源组件:选择营销云适配器,接口选 query/saleReturnOrder,idCheck 开启,主键字段为 number,避免重复拉取。
2. 增量水位:用 {{LAST_SYNC_TIME\|datetime}} 注入 beginTime,endTime 取当前时间,平台自动记录本次最大更新时间作为下次起点。
3. 数据清洗:在轻易云的「字段映射」面板集中维护编码映射,这是轻易云客户最常见的应对模式——编码映射集中管理,后续同类单据直接复用,改一处全局生效。
4. 客户主键查找:目标端 customer_id 不接受编码,用 _findCollection find id from ... where number={{extCusCode}} 走「按编码查主键」的标准动作,失败时进入错误队列人工补齐。
5. 目标组件:金蝶云星辰适配器选 sal_in_bound,bill_source 写死 ISV,remark 拼上「来自营销云-单号」便于溯源。
6. 幂等:目标端 idCheck=true,以 id 作为幂等键,即使重跑也不会重复入库。

实施步骤

我们一般建议客户按三个阶段推进:

阶段一:增量起点初始化。首次上线前,手工确认一个合理的 beginTime(通常是上线当日 00:00:00),先用全量方式把历史退货单补齐;之后所有日常运行都走增量。

阶段二:全量触发与对账。上线第一天,先手动触发一次全量,对照两边单据编号和金额;轻易云会自动落日志,跑完拉一份「源/目标」对账报告,差异单据逐单排查。这一步不要跳过,增量与全量双轨是轻易云项目里反复验证过的稳态模式。

阶段三:日常调度。源端每 8 分钟、8-21 点拉一次(*/8 8-21 * * *),目标端每 7 分钟、7-23 点写一次(*/7 7-23 * * *),错峰轮询,避免两边在同一秒集中请求。夜间停跑既符合业务作息,也减少无效调用。

踩坑复盘

1. status 没传或传错:典型错误是默认全量拉,把未审核的草稿也同步过去,导致金蝶端出现大量作废单。这里稳妥的做法是源端 status=1 写死,并在轻易云「过滤条件」里再加一道。
2. beginTime 没做时区处理:营销云返回的是带时区的时间字符串,如果不 |datetime 标准化,跨天时会出现「同一条单据被拉两次」或「漏单」。一定要在映射层显式格式化。
3. 客户主键查找失败:经销商编码在星辰里被改过名,直接用编码查不到。这里建议在轻易云里维护一张「编码→客户ID」兜底映射表,查不到时回退到该表,并打日志告警。
4. 重跑导致重复入库:虽然开了 idCheck,但如果源端同一 number 在审核后又修改过明细,目标端可能因为 id 不一致被当成新单。这里要把源端业务单号 number 也写进 remark,方便人工对账。
5. 夜间调度把未审核变更同步过去:如果源端夜里有「反审核-改单-再审核」操作,增量会把这段时间窗内的多次变更都拉过来。稳妥的做法是在轻易云里先做表头、再做表体,分阶段提交,出现异常时分段回滚,避免整单全废。

适用场景与不适用场景

适用:退货流程在营销云、库存与财务在金蝶云星辰的零售/分销企业,日单量几十到几千、退货单需要实时回流库存的场景。不适用:源端退货流程未固定、状态字段含义多变的早期系统,以及需要双向同步(星辰退货也要回写营销云)的复杂链路——后者建议拆成两条独立策略,避免循环依赖。