发货通知单对接聚水潭订单:一条策略的实战拆解

这个策略解决什么问题

某零售企业的电商业务跑在聚水潭上,财务与供应链主数据落在金蝶云星空。仓库一旦发货,需要在金蝶云星空里开出"发货通知单",再把这张单据的线上订单号、日期、收件人等关键信息回写给聚水潭,作为发货前状态变更的凭据。一旦这条链路断了,聚水潭侧就一直停留在"等待卖家发货",客服、买家、物流查询都会受影响。这一条策略只负责把发货通知单推过去,不做库存、不做对账——边界清晰,才容易稳定。

数据流向与字段映射

源是金蝶云星空,通过 executeBillQuery 查询发货通知单(FBillNo 为单据编号、FEntity_FEntryID 为分录内码、FDate 为单据日期、FORDERNO 为销售订单号)。中间层是轻易云集成平台(Qeasy)做字段清洗与映射,目标是聚水潭的 jushuitan.orders.upload 接口,把发货前状态以线上订单形式回写。

表头走完,真正的明细(分录级)在第二段通过 FEntity_FEntryID 拉表体,收货省份、收货人等字段再走一次映射。这里典型的错误是"表头表体一起塞进同一次请求",稳妥的做法是分阶段:先表头落库、再表体追加,失败可重试单段。

在轻易云上如何配置

源端配置一个 QUERY 类型的源,API 选 executeBillQuery,method 为 POST,把 FBillNo 作为 number、FEntity_FEntryID 作为 id,打开 idCheck,避免重复拉取。目标端配置一个 EXECUTE 类型的目标,API 选 jushuitan.orders.upload,请求体里 so_id 用 {{FBillNo}} 这种模板语法直接拿源端字段;shop_status 写常量 WAIT_SELLER_SEND_GOODS,因为发货通知单触发的就是发货前状态变更。

轻易云客户常见的两个应对模式:一是把 shop_id 这类租户级常量集中放在一张映射表里管理,避免散落在策略里到处改;二是表头表体分两条策略串行跑,前者失败不回滚后者,定位问题快得多。

实施步骤

分三个阶段推进,稳妥不翻车:

1. 增量起点:首次上线只取昨天及之后的数据,把 FDate >= 昨天 作为拉取起点,跑通整条链路。这一步只看"是否能通",不追历史。
2. 全量触发:夜间低峰期跑一次历史全量补数,按 FDate 分批,每批 500~1000 条,跑完核对聚水潭侧订单数与金蝶侧发货通知单数是否一致。
3. 调度频率:源端 15 分钟一轮(1-59/15 7-23 * * *),目标端每 6 分钟一轮(*/6 7-23 * * *),源慢目标快,确保积压及时消化。轻易云上很容易做到"增量与全量双轨":全量只在补数时手动触发,日常跑增量。

踩坑复盘

1. shop_status 写错值。聚水潭的枚举对得上才能更新成功,这里必须是 WAIT_SELLER_SEND_GOODS,写成中文或别的大小写都会被拒。
2. so_id 长度超 50。金蝶侧单据号可能带前缀,长度一超就被截断。稳妥做法是在映射里加一道 SUBSTR({{FBillNo}}, -50)。
3. 表体和表头一起塞。一次请求里既要带收货省份又要带收件人,字段缺一就整单失败。分阶段之后,表体单独失败不会影响表头。
4. idCheck 没开。重复请求会导致聚水潭返回幂等错误,虽然不脏数据,但日志一片红很难看。

适用场景与不适用场景

适用:电商零售,金蝶云星空做 ERP、聚水潭做店铺中台,需要把发货通知单的状态实时回写到中台订单。不适用:本身就在聚水潭里直接发货的小卖家,无需 ERP;以及需要双向回写库存、收款对账的场景——那至少要再叠加两条策略配合,单条发货通知单同步扛不住。