销售出库单同步——取运费单实战教程(聚水潭 → 金蝶云星空)

这个策略解决什么问题(场景与价值)

某零售企业的电商业务跑在聚水潭上,ERP 财务核算在金蝶云星空里。仓库发货后,运营希望把已确认的销售出库单(含运费单信息)按节奏推到星空,作为后续开票和对账的依据。这条策略只做一件事:增量拉取聚水潭已出库单据,补齐运费单、运输单号等头信息,写入星空销售出库单。看似只有一条策略,但运费字段的来源与口径一旦没想清楚,3 个月后两边运费总额会对不上,财务就只能回头翻单。

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

源系统是聚水潭,目标系统是金蝶云星空。在轻易云数据集成平台(Qeasy)上,中间会经过统一的请求/响应中转层,把源字段写成目标能认的字段。

源侧主调用为 jushuitan.saleout.list.query,按 start_time / end_time 做增量窗口,只取 status=Confirmed(已出库)的单据,以 io_id 作为单据主键。目标侧调 batchSave 写入,单据类型固定 XSCKD01_SYS。

关键字段对照(节选):

运费单信息在聚水潭里不是出库单的顶层字段,而是嵌套在运费段里。这里很容易翻车——很多人按主单字段直接映射,运费就丢了。

在轻易云上如何配置

在 Qeasy 上配置这条策略,要点有四:

第一,源接口选 jushuitan.saleout.list.query,分页参数 page_index 默认 1,page_size 按源系统上限给到 50。注意源系统的分页硬上限,超过会被截断。

第二,增量时间窗用平台的内置变量 {{LAST_SYNC_TIME|datetime}} 和 {{CURRENT_TIME|datetime}},平台自动维护水位。

第三,运费字段单独建一条取数分支,不要和主单字段混在同一条 SQL/脚本里。轻易云常见的应对模式之一就是把"表头"和"运费/表体"分阶段处理:先取主单落中间层,再把运费段拼接上去。

第四,编码映射集中管理。shop_id 到 FCustomerID、FSaleOrgId 的对照关系放进统一的映射表,后续别的策略(物料、店铺)直接复用,避免一处改、处处漏。

实施步骤(分阶段调度)

1. 增量起点:首次上线用一个小时间窗(如最近 2 小时)作为 start_time,先验证链路。典型错误是一上来就拉 7 天全量,源系统分页和目标限流会直接打满。
2. 全量触发:历史数据用一次性全量任务单独跑,与增量任务错开时段,避免互相抢占。
3. 调度频率:源策略 crontab 设成 22 */2 * * *(每 2 小时的第 22 分钟),目标写入 10 0 * * *(每天 0:10)。两边错峰 30 分钟以上,给目标系统留出处理窗口。
4. 复跑机制:保留最近 7 天的水位快照,出现漏单时可以按单据号补拉,而不是重跑整段。

踩坑复盘

• 时间窗超过 7 天:源接口硬性约束 start_time 与 end_time 间隔不能超过 7 天。一次性全量必须切成多段跑。
• 运费段被忽略:运费信息嵌在运费单里,不是顶层字段。映射时务必显式取运费段的值。
• status 取错:把 WaitConfirm(待出库)推过去,目标系统会拒收或产生空运费单。
• 单据号重复:源端 io_id 必须做幂等写入,目标端按 FBillNo 判重,避免重跑产生重复出库单。
• 组织/客户编码没登记就推:星空对 FSaleOrgId、FCustomerID 是强校验,编码映射表里没登记就报错。建议上线前一次性把客户和组织映射补齐。

适用场景与不适用场景

适用:电商零售、已用聚水潭做仓库发货、希望把已出库单和运费信息推到 ERP 用于开票对账的企业。不适用:需要实时出库(分钟级)的场景、聚水潭未确认状态的预出库业务,以及多组织、多账套的复杂分销链路——后者需要先拆账套再谈同步。