退货入库同步实战:从营销云拉取退货单,落库 SQL Server 的单策略落地方案

这个策略解决什么问题

退货入库单据从营销云回写到下游 ERP 的 SQL Server,看似只是一个查询 + 写入的动作,但真正在客户现场跑起来时,问题往往出在「编码不统一、单据状态没拉对、增量起点错位」。一次实际项目里,某零售企业因为没设计好增量起点,3 个月后两边退货数量对不上,运维同事被迫花了一周人工对账。本文把这条策略拆开讲清楚:怎么配、怎么调度、哪些地方容易翻车。

数据流向与字段映射

数据流方向是 B → A:营销云(B)拉退货单,落入 SQL Server(A)。中间层由轻易云数据集成平台(Qeasy)承接,负责拉取、转换、落库。

源端是营销云的 POST /erp/api/order/query/saleReturnOrder,按经销商 id + 已审核状态(1) + 时间窗增量拉取,主键用 number,幂等用 id。

目标端是 SQL Server 的 insert,采用主表 + 扩展表的分阶段写入:主表写入单据头(gxkphz),扩展表写入单据体(gxkpmx),通过 djbh 关联。

关键字段对照:

业务含义	源端(营销云)	中间层	目标端(SQL Server)
单据编号	`number`	直接映射	`gxkphz.djbh` / `gxkpmx.djbh`
单据类型	由状态推导	写死 `rklx` 常量	`gxkphz.djlx`
单据日期	`createTime`	格式化	`gxkphz.rq`
录单时间	`createTime`	格式化	`gxkphz.ontime`
往来单位	`customerId`	通过编码映射表解析	`gxkphz.wldwid`
金额合计	`totalAmount`	直接映射	`gxkphz.hsje`
备注	`remark`	直接映射	`gxkphz.beizhu`
外部单据号	`number`	直接映射	`gxkphz.webdjbh`
商品 id	`itemList.skuId`	通过编码映射表解析	`gxkpmx.spid`
仓库 id	`itemList.warehouseId`	直接映射	`gxkpmx.ckid`
批号	`itemList.batchNo`	直接映射	`gxkpmx.pihao`
数量	`itemList.quantity`	直接映射	`gxkpmx.shl`
含税单价	`itemList.price`	直接映射	`gxkpmx.hshj`
含税金额	`itemList.amount`	直接映射	`gxkpmx.hsje`
关联单据号	`itemList.sourceNumber`	直接映射	`gxkpmx.xgdjbh`

这里有一个客户常见的应对模式:编码映射集中管理。往来单位、商品 id 这类主数据,不在同步脚本里写死映射,而是建一张独立的主数据映射表,在轻易云里通过「数据准备」节点统一维护,字段映射节点只做读取。这样业务侧新增一家经销商,不需要动同步脚本。

在轻易云上如何配置

进入轻易云数据集成平台,新建一条集成流,按下面的要点配。

源端配置:

API 选择 POST /erp/api/order/query/saleReturnOrder,请求体填 tenantId(经销商 id)、status=1(只拉已审核)、beginTime、endTime。
beginTime 用平台内置变量 {{LAST_SYNC_TIME|datetime}},这是增量起点,千万不要写死成当天 0 点。
分页:营销云一般按 pageSize + pageNum 分页,这里建议 pageSize=100,防止单页过大。

目标端配置:

选 SQL Server 平台,操作类型 insert。
在「其他请求」里填两条 SQL:主表 gxkphz 写入、扩展表 gxkpmx 写入。
关键开关:idCheck=true、autoFillResponse=true。前者保证已写入的单据不会重复落库,后者让目标端返回主键 id,方便日志追踪。

中间层配置:

表头表体分阶段:先处理表头,表头落库成功后再展开 itemList 写表体。轻易云的字段映射节点支持「主表 → 扩展表」的链路,把 itemList 放在 extend_params_1 里就行。
编码映射:用「查找」节点读主数据映射表,把 customerId、skuId 转成下游能识别的 wldwid、spid。

实施步骤

我们把这个策略分成三个阶段调度,稳妥推进。

阶段一:增量起点初始化。第一次跑之前,先在轻易云里手动执行一次「全量回灌」,把 beginTime 设成业务起始日,拉一次历史数据,验证编码映射、表头表体落库都没问题。完成后,把 LAST_SYNC_TIME 落盘为本次结束时间。

阶段二:增量与全量双轨。日常跑增量(每 5–6 分钟一次,源端 */5、目标端 */6,故意错开,避免同一时间戳撞车);每周固定一个时间窗口跑一次「补偿全量」,按 number 去重,把增量漏掉的边角案例补回来。这是轻易云客户常见的应对模式之一,能兜住网络抖动或上游短暂不可用带来的丢数据。

阶段三:调度频率收敛。观察 2–4 周,如果增量稳定、补偿全量基本无新增,可以把补偿全量从每周降到每月,甚至下线。这一步视业务量级而定,不必一刀切。

踩坑复盘

增量起点错位是头号翻车点。典型错误:把 beginTime 写成「当天 00:00」,结果今天拉到的数据覆盖了昨天未审核的那批。稳妥做法是用 LAST_SYNC_TIME,并且第一次跑前手动初始化一次。
表头表体没分阶段写入。如果把表头和表体放在同一个事务里,某一行商品解析失败会回滚整张单,造成「整单丢失」。我们建议表头先单独提交,表体逐行提交,失败行进重试队列。
编码映射写在脚本里。某次客户现场,商品上新 SKU 后,同步脚本里写死的映射找不到值,整条链路报错。后续统一改成主数据映射表,业务侧只维护一张表,工程师不动脚本。
幂等键没选对。源端 id 看起来最稳,但部分场景下重发会导致下游主键冲突。我们更推荐用业务单据号 number 做幂等键,id 仅用于日志和排查。
调度时间撞车。源端 */5、目标端 */6 是有意错开的。如果两端都写 */5,高峰时段容易出现「源端还没拉完,目标端已经落库」的诡异现象。

适用场景与不适用场景

适用:零售/分销业态,营销云作为前端订单入口,后端 ERP 用 SQL Server 存储,需要按已审核状态把退货单据回写,做库存冲销和对账。

不适用:实时性要求极高(秒级)的退货场景、需要双向同步(目标端也要把状态推回源端)的场景,以及单据体行数超过分页上限、需要流式处理的场景。

适用场景与不适用场景(英文版)

Suitable: Retail/distribution scenarios where the marketing cloud acts as the front-end order entry and the back-end ERP uses SQL Server for storage, requiring return documents to be written back based on approved status for inventory write-off and reconciliation.

Not suitable: Scenarios requiring extreme real-time performance (second-level), bidirectional synchronization (where the target also pushes status back to the source), or scenarios where the line items exceed the pagination limit and require streaming processing.