采购入库同步实战:营销云单据到金蝶云星辰落地的踩坑全记录

这个策略解决什么问题

某零售企业的营销云系统对外管理经销商采购订单的创建与审核状态,金蝶云星辰负责后端库存与应付核算。采购入库单需要把营销云已审核的入库记录落到金蝶云星辰,作为入库与核算的起点。源单据按时间窗增量拉取,避免业务高峰时全量重跑造成目标系统拥堵与重复入库。

数据流向:营销云(采购入库单) → 轻易云中间层 → 金蝶云星辰(采购入库单)。

关键字段对照表(已脱敏):

业务含义	营销云源字段	中间层处理	金蝶云星辰目标字段	备注
单据号	number	直接映射	bill_no	源端全局唯一,作为幂等键
单据日期	auditTime	格式化为日期	bill_date	用审核时间而非创建时间
业务类型	transtype	静态映射	transtype	目标侧固定值
供应商编码	supplierId	经销商→供应商映射表	supplier_id	编码映射集中维护
备注	remark	拼接原单号	remark	拼上源单号便于追溯
表体商品行	items[]	逐行展开	entries[]	表头表体分阶段处理

编码映射集中管理是轻易云客户常见的应对模式之一:供应商、商品等主数据先经过一次基础资料同步策略落地,采购入库只引用编码,不重复建档,降低目标侧脏数据风险。

在轻易云数据集成平台(Qeasy)中,这条策略属于「采购订单同步」域下的入库子策略,典型配置要点如下:

源端接入:WebAPI/POST,接口地址指向营销云的采购入库查询接口,带经销商id(tenantId)与状态过滤(status=1 已审核)两个核心入参。
时间窗:beginTime 用变量 {{LAST_SYNC_TIME|datetime}},endTime 取当前时间,保证每次只拉上次同步点之后的数据。
目标端接口:WebAPI/POST,对接金蝶云星辰的采购入库创建接口,transtype 按目标系统枚举写入。
字段映射:供应商、商品编码走「查找映射」节点,而不是直接传值,这样源系统编码调整时只需要刷新映射表。
幂等控制:开启 idCheck,以源端单据号作为幂等键,目标侧重复推送自动跳过。
异常处理:失败重试 3 次,仍失败的单据进入「异常队列」,由人工补单或触发反向回查。

阶段一:增量起点校准。上线前一次性全量拉取历史已审核入库单,写入目标系统;同时记录 LAST_SYNC_TIME 初始值,确保增量从这一时间点之后开始。建议放在业务低峰期执行,避免与日常调度冲突。
阶段二:全量触发与对账。全量跑完后,在目标系统导出当批次入库单号,与源端比对,确认无遗漏、无重复,确认无误后再开启定时调度。
阶段三:日常调度。源端拉取调度设到工作日的白天时段(参考素材中 8-21 点每 5 分钟一次),目标端写入设到稍晚的时段(7-23 点每 5 分钟一次),两者错开分钟级窗口,避免同一时间两边的写压力叠加。
阶段四:监控与异常处理。在轻易云上配置运行时长、失败条数、空包三类监控阈值;出现连续空包时,要排查源端接口是否限流或鉴权过期。

增量与全量双轨是轻易云客户常见的另一种应对模式:首次上线全量兜底,日常增量跟跑,两者用不同的调度任务,既保证历史数据完整,又避免每次全量扫表。

时间窗用错字段。典型错误是用「创建时间」做增量窗口,导致源端先创建后审核的单据被漏掉。稳妥的做法是用 auditTime(审核时间),与目标系统的「已审核入库」语义一致。
供应商编码直接传源系统 id。源系统是字符串经销商id,目标系统是数字供应商id,直接传值会导致目标侧建出垃圾供应商档案。必须经过映射表转换。
表头表体一次性提交。源端表体较大时,一次性把整张单提交到目标系统容易触发超时。把表头先落,再用子流程逐行写表体,是表头表体分阶段处理的常见做法。
幂等键选错。用源端 id 重复入库会出现「重复创建」错误。稳妥的做法是用源端业务单号(number)作为幂等键,并开启 idCheck。
两端调度时间重叠。源端拉取与目标端写入挤在同一分钟,源端还没拿到数据,目标端就已经开始往目标系统写,造成空包。错峰调度是基本功。

适用:源系统有明确的「已审核」状态,目标系统需要按时间窗增量同步,且双方都有标准的采购入库 API。不适用:源系统状态字段语义模糊、目标系统要求强实时秒级同步、或者双方都没有稳定的 API 通道,这类场景需要先补齐基础数据与接口,再考虑同步。