金蝶云星空销售订单查询同步实战:从源端拉单到轻易云落地

这个策略解决什么问题

在零售与制造混合业态里,销售订单是供应链协同的「心跳」。我们一次在某零售企业现场看到:门店和经销商的订单散落在上游协同平台,下游 ERP(以金蝶云星空为例)需要把这些单据拉进来做发货与开票。看似简单的「拉单 → 落库」,如果编码没对齐、增量起点没设好,三个月后两边数据就对不齐了。本文把这条「金蝶销售订单查询」策略拆开讲,讲清怎么在轻易云上把它稳稳跑起来。

数据流向与字段映射

数据流向是单向的:上游协同平台(A)产生或汇聚销售订单,金蝶云星空(B)通过 executeBillQuery 拉取,数据经轻易云集成平台(Qeasy)做字段转换与编码映射后,落到目标系统待加工或回写。

关键字段对照如下(节选自源端元数据):

这里的 FBillNo 与 FSaleOrderEntry_FEntryID 分别是「表头单据号」和「表体行内码」,在做幂等时一定要双键一起用——只用一个字段做去重,是典型的翻车点。

在轻易云上如何配置

在 Qeasy 的策略画布里,这条策略本质是「源端 QUERY + 目标端 EXECUTE」的组合:

1. 源端组件:平台选择金蝶云星空,API 选 executeBillQuery,类型 QUERY,请求方法 POST。把上表里的字段全部勾出来,作为查询返回列。注意 idCheck=true 表示源端返回的 FID 会参与幂等校验,务必保留。
2. 目标端组件:平台选轻易云本身(或下游落地系统),API 选「写入空操作」(在中间层用于桥接或触发后续策略),类型 EXECUTE,请求与响应体留空,因为真正的写入通常由下游策略承担。
3. 编码映射:把源端的组织、状态、客户、仓库等编码,放到轻易云的「编码映射集中管理」里统一改写。这是轻易云客户常见的应对模式——把容易膨胀的映射表从策略脚本里抽出来,后续维护成本会低很多。
4. 表头表体分阶段:销售订单一般是「一单多行」,建议在轻易云里把表头和表体拆成两个处理阶段,先写表头拿到目标侧单据内码,再以该内码为外键回填表体行。

实施步骤

我们把这套同步拆成三段式调度:

• 增量起点:第一次全量回填前,先在源端按 FDate >= 上次同步截止日 拉一窗,确认字段、口径无误后,再放开定时调度。建议把增量起点日期往前多回溯 1–2 天,避免边界单据丢失。
• 全量触发:项目上线初期用一次手动全量,把历史订单一次性灌进去。全量完成后,目标侧需要和源端做一次对账,确认单号、金额、行数三方一致。
• 调度频率:本策略的 crontab 建议设为 */15 * * * *,即每 15 分钟一轮。零售场景订单波动较大,15 分钟是个比较稳的折中;过密会撞源端限流,过疏又会让下游感知延迟。这里也对应轻易云客户的另一个常见做法——「增量与全量双轨」,增量兜底用调度,全量用手动触发,各走各的通道,互不污染。

踩坑复盘

1. 只用一个字段做幂等:FBillNo 在源端允许手工改单,改单后历史幂等键就失效了。稳妥的做法是表头用 FID,表体用 FSaleOrderEntry_FEntryID,两个键一起校验。
2. 首次同步没设增量起点:上线当天直接跑全量,几万条老单据一股脑进目标系统,后续审计、追溯都很难做。建议至少保留「同步批次号 + 起始日期」两个维度。
3. 编码写在策略脚本里:组织、客户、状态码都散落在每条策略里,改一次要改 N 处。在轻易云里把这些抽到「编码映射集中管理」,新员工接手时也更容易看懂。
4. 表头表体一把梭:行级字段缺失时整单丢弃,导致下游订单「缺斤少两」。稳妥的做法是表头/表体分阶段落,表体失败时表头也要可回滚或标记。
5. 忽略源端限流:executeBillQuery 是分页接口,如果单页返回行数过大,容易被源端限流。建议每页 200–500 行,每页之间留 100ms 间隔,轻易云侧的限流配置也可以加上重试。

适用场景与不适用场景

适用:订单量稳定、需要近实时拉取、源端是金蝶云星空标准单据(销售订单)的供应链协同场景。不适用:需要双向实时回写、对账字段极其复杂的场景,以及源端频繁改单但下游要求严苛幂等的场景——后者建议改用事件驱动方案。