聚水潭与金蝶云星空供应链集成接口字段手册：从商品主数据到销售出库全链路实战
这个接口解决什么问题
在电商与 ERP 双系统并存的零售企业里,聚水潭管前端的店铺、订单与库存流水,金蝶云星空管后端的物料、供应商、采购与财务核算。两边不互通就会导致商品编码重复、库存数对不上、采购订单漏传、销售出库进不了财务。我们聚合了多客户落地经验,把这条「商品/供应商主数据 → 采购订单/入库/退货 → 销售出库」的双向同步链路沉淀成一份接口字段手册,让你无需翻遍多个方案也能一次掌握关键设计模式。
接口能力总览
认证方式:聚水潭侧采用 app_key + app_secret 的开放平台签名鉴权;金蝶云星空侧采用基于数据中心 ID + 应用 ID 的 OAuth2 / Bearer Token 流程,租户票据有效期通常需做刷新缓存。
请求结构:聚水潭奇门/非奇门接口以 form 或 JSON 形式传入 page_index / page_size / modified_begin / modified_end;金蝶云星空则通过 formId(如 BD_MATERIAL、PUR_PurchaseOrder、SAL_OUTSTOCK)+ 业务参数 + OrgId 组织过滤的方式查询。
响应结构:两边均返回分页数据(行项目数组 + 总数),金蝶响应需注意 Result 外层包裹与 ResponseStatus 成功标识;聚水潭响应中 data 字段再嵌套 items 与 has_next。
分页与增量模式:聚水潭增量字段以 modified_begin/modified_end 为主,销售出库也可按 pay_date 过滤;金蝶增量优先使用审核日期 FApproveDate,辅以 FModifyDate。首次部署必须跑全量回填,后续按 LAST_SYNC_TIME 滑窗拉取。
典型字段映射
| 域 | 源字段(举例) | 目标字段(举例) | 类型 | 实战注意事项 |
|---|---|---|---|---|
| 商品主数据 | 金蝶 FNumber | 聚水潭 sku_id/i_id | DIRECT | FNumber 同时作为款式编码;unit 固定填 Pcs;增量按 FApproveDate,过滤 F_QKMS_JSTBM 非空 |
| 商品主数据 | 金蝶 FName / FSpecification | 聚水潭 name / properties_value | DIRECT | 规格缺失时回退编码 |
| 供应商 | 金蝶 FNumber | 聚水潭 supplier_id | DIRECT | 增量按 FModifyDate;按组织(绿健/爱梨)分策略 |
| 采购订单 | 金蝶 FBillNo | 聚水潭 po_id | DIRECT | FEntryTaxRate 需 round(/100,2) 转小数 |
| 采购订单 | FSupplierId_FNumber / FStockId_FNumber | supplier_id / wms_co_id | COLLECTION | 必须先建好编码映射表再下单据 |
| 采购入库(关联) | 金蝶 FSRCBillNo | 聚水潭 po_id | COLLECTION | 联查采购订单映射表;is_confirm=0、excute_confirming=false 防误审 |
| 采购入库(不关联) | 金蝶 FBillNo | 聚水潭 po_id | DIRECT | 无源单时用自身单号兜底 |
| 采购退货 | 金蝶 FSRCBillNo | 聚水潭 remark | TRANSFORM | 拼接「金蝶采购入库单号:xxx」便于追溯 |
| 其他出入库 | - | type | CONSTANT | 出库填 out,入库填 in |
| 盘盈/盘亏 | FGainQty / FLossQty | qty | DIRECT | 字段名容易看错,务必区分 |
| 销售出库 | 聚水潭 io_id | 金蝶 FBillNo | DIRECT | FBillTypeID 固定 XSCKD01_SYS |
| 销售出库 | 聚水潭 shop_id | 金蝶 FCustomerID | COLLECTION | 必须做店铺→客户映射,多店铺拆分策略 |
| 销售出库 | 聚水潭 so_id / l_id / logistics_name | 金蝶 FSALECHANNEL / 自定义字段 | DIRECT | 自定义字段名以 F_QKMS_ 开头,先在金蝶建模 |
在轻易云上如何配置
在轻易云数据集成平台里,这套方案通常拆为「聚水潭连接器 + 金蝶云星空连接器 + 编排调度」三层。聚水潭连接器内置了 jushuitan.saleout.list.query 等常用接口模板,可以直接选模板、再改 shop_id 过滤条件;金蝶云星空连接器则提供 BD_MATERIAL、PUR_PurchaseOrder、SAL_OUTSTOCK 等表单的预设 schema,OrgId 可作为连接属性绑定。
编码映射(物料/供应商/仓库/店铺→客户)在轻易云里用「字段映射器」维护,支持手工建表、SQL 同步、Excel 导入三种方式;轻易云的字段映射器会自动校验源字段与目标字段的类型,例如把金蝶 FEntryTaxRate(百分比)按自定义函数 round(x/100,2) 落到聚水潭 tax_rate(小数),无需写代码。
调度策略上,平台会把「查询类」放到基础资料任务组,业务单据按依赖顺序串成 DAG;失败队列与重试退避策略是开箱即用的,单条失败不会阻塞后续批次。
跨方案实战要点
- 基础资料永远先行:商品、供应商、仓库的查询与同步必须排在业务单据之前,否则
sku_id、supplier_id、wms_co_id落不到目标端。 - 编码映射是命门:物料、仓库、店铺→客户的映射表要提前维护并支持双向回查,金蝶的
F_QKMS_JSTBM等自定义字段务必先在金蝶建模,再在聚水潭侧过滤。 - 多店铺要拆策略:聚水潭不同
shop_id对应不同金蝶客户/组织,我们看到的所有方案都对每家店铺单独配一条策略,而不是用一条规则硬切,便于排错与差异化税率配置。 - 入库单关联 vs 不关联分开走:有源采购订单时务必联查映射表拿
po_id;无源单场景必须兜底用FBillNo自己当po_id,避免目标端校验失败。 - 增量字段要选对:金蝶优先用
FApproveDate(审核日期)而不是FModifyDate,否则改单后会被反复拉取;聚水潭销售出库可叠加pay_date二次过滤。 - 不自审、不自确认:聚水潭侧
is_confirm=0、excute_confirming=false几乎成为行业默认,先写入、再人工审核能大幅降低误操作风险。
踩坑复盘
- 采购入库单把
FBillNo写到了po_id:关联场景必须用FSRCBillNo联查采购订单,否则会出现「入库单存在但找不到对应采购单」的悬空数据。稳妥的做法是优先联查,联查不到再回退。 - 税率没除 100:金蝶
FEntryTaxRate是百分比(例如 13),聚水潭要的是小数(0.13),直接透传会导致金额翻倍,这里一定要加round(x/100,2)。 - 盘盈盘亏字段名搞混:
FGainQty是盘盈数量、FLossQty是盘亏数量,虽然只差一个字母,但落到金蝶入库或出库方向完全不同,务必按策略逐条核对。 - 店铺→客户映射漏配:某项目 21 家店铺只配了 5 家,导致剩下店铺的销售出库全失败;建议接入前一次性建表,跑一条「覆盖率」校验脚本。
- 金蝶自定义字段未建模:金蝶侧的
F_QKMS_XKDDH(快递单号)、F_QKMS_KDGS(快递公司)等字段若未先在金蝶建模,集成平台推过去会被直接丢弃,白白浪费重试配额。
何时选用
这套模式适用于「电商 ERP + 财务 ERP」双系统并存、且需要打通商品/供应商主数据与采购/销售单据的中大型零售或分销企业。如果你的库存与财务核算全部在单系统内,或主数据来源只有一方,就不必上这套双向链路,单方向同步即可。涉及多组织、多店铺、跨税务主体时,这套字段手册也能直接套用。