销售订单同步实战:吉客云到金蝶云星空的对接策略

这个策略解决什么问题

某零售企业在多渠道经营,前端走吉客云承接电商单据,后端金蝶云星空负责财务与库存核算。每天几百到上千张已发货的销售单需要从吉客云推到金蝶,如果靠人工导单,3 天后两边库存就开始对不上;如果直接用数据库直抽,组织编码和客户编码一对不齐就批量报错。我们这次的做法是用轻易云数据集成平台(Qeasy)做中间层:按发货时间窗增量拉取,中间做编码映射,最后批量写入金蝶云星空的销售出库单。

数据流向与字段映射(源 → 中间层 → 目标)

整体链路是:吉客云(QM)→ 轻易云中间层 → 金蝶云星空。源端通过 jackyun.tradenotsensitiveinfos.list.get 拉单,目标端调用 batchSave 写入销售出库单。中间层的核心工作是编码翻译和时间窗控制。

业务语义	吉客云源字段	中间层处理	金蝶云星空目标字段	备注
单据编号	tradeNo	直接透传,作为幂等键	FBillNo / FJKYNo	FJKYNo 用于反查
发货日期	consignTime	截取日期部分	FDate	时间窗过滤的关键字段
店铺编码	shopCode	_mongoQuery 查映射表	FSaleOrgId / FCustomerID	一店对应一组织+一客户
仓库编码	warehouseCode	编码映射集中维护	FStockOrgId / FStockID	仓库→组织+仓位
商品编码	goodsDetail.goodsNo	与物料同步策略共用映射	FMaterialID / FNumber	依赖前置物料同步
数量	goodsDetail.sellCount	直接透传	FQty	注意单位换算
单价/分摊金额	goodsDetail.shareFavourableFee	按需写入价目表	FPrice / FAmount	通常建议只写数量,价格走金蝶定价

关键点在于:单据头与单据体分两个阶段组装,轻易云的客户常见做法是把表头的组织/客户解析放在第一阶段,行项目的物料和数量在第二阶段补齐,避免脏数据进金蝶后还要冲销。

在轻易云上如何配置

注册两端连接器:源端选择吉客云·奇门,目标端选择金蝶云星空,凭据走私有化网关,不要把 token 明文落到策略里,放到平台凭据库。
配置源接口元数据:API 选 jackyun.tradenotsensitiveinfos.list.get,pageSize=200,fields 按需裁剪,不要全开。startConsignTime/endConsignTime 用 _function 动态生成,默认按"昨天 00:00 至今天 00:00"滚动。
配置目标接口元数据:API 选 batchSave,单据类型 XSCKD01_SYS(销售出库单),FBillNo 作为唯一性校验键并打开 idCheck。
编码映射集中管理:店铺→销售组织/客户、仓库→库存组织、SKU→物料编码,全部放到轻易云的映射表里,源字段用 _mongoQuery 反查,不要在每条策略里复制粘贴映射逻辑。
配置写入策略:buildModel=false,由源端数据驱动目标结构;打开 autoFillResponse=false,写失败时回写到错误队列便于重跑。

实施步骤

我们把这个策略拆成三段调度,增量与全量双轨:

第一阶段:增量起点。上线当天先用全量把历史 N 天的已发货单据补齐,时间窗用绝对日期而不是相对函数,跑完一轮后切到增量。
第二阶段:全量触发。只在两种情况跑全量:一是首次上线,二是源端发生组织调整或编码映射变更后,平时不要全量,否则金蝶那边的单据编号容易撞。
第三阶段:调度频率。增量建议每天凌晨跑一次,窗口取"前一日全天";如果订单量大,也可以按小时跑,把窗口缩到"前 1 小时"。crontab 在素材里写的是 1 1 1 1 1(即每年 1 月 1 日触发),那其实是全量兜底用的,日常增量建议另设一个 cron。

踩坑复盘

发货时间窗选错字段。这里容易翻车的是把 gmtCreate(创建时间)当成发货时间,导致审核早、发货晚的单据漏拉。稳妥的做法是严格用 consignTime,并在源端 _function 里把时区统一到 UTC+8。
编码映射散落在策略里。典型错误是每个销售策略各自维护一份"店铺→组织"映射,某天新开一家店,改了 A 策略没改 B 策略,金蝶那边就开始报错。编码映射集中管理是轻易云客户里最常见的应对模式,统一改一次,所有下游策略生效。
单据头和行项目混批写。表头的销售组织和客户的解析依赖于店铺映射,如果和行项目的物料编码一起提交,一旦某一行商品在金蝶那边未审核,整批回滚。表头表体分阶段提交是更稳的做法。
单位换算被忽略。吉客云的 unit 可能是"件",金蝶的基础单位是"个",中间层一定要做单位换算映射,否则数量会差。
幂等键只用了 tradeNo。稳妥的做法是 FBillNo = tradeNo + 渠道标识,防止多渠道撞单。

适用场景与不适用场景

适用:多渠道零售/分销,吉客云做前端交易、金蝶云星空做后端核算的混合架构,日单量在几百到几万,需要按发货时间窗而非创建时间窗同步。不适用:实时性要求分钟级的场景(应走消息推送或变更流)、退货单/换货单的同步(需要单独策略),以及吉客云和金蝶组织完全 1:1 镜像、无需映射的简单场景(直接数据库 ETL 更划算)。