聚水潭与金蝶云星空供应链集成接口字段手册权威教程
这个接口解决什么问题
聚水潭（电商 ERP）与金蝶云星空（企业 ERP）的供应链集成，是电商零售企业实现"线上销售—库存联动—财务核算"闭环的核心环节。该接口族解决三大问题：电商销售出库/退货自动同步至金蝶形成财务凭证、采购与库存业务从金蝶回流聚水潭保证库存一致、基础资料与编码在两套系统间保持统一。
接口能力总览
认证方式：聚水潭采用 AppKey+AppSecret 的签名机制；金蝶云星空采用第三方登录接口换取 SessionToken 后调用业务接口。
请求/响应结构：聚水潭接口以 JSON 为主，支持分页（page_index/page_size）与时间窗（modified_begin/modified_end）增量；金蝶接口以 FormId+JSON 为主，需通过 Operation（Save/BatchSave/Submit/Audit）链式操作完成单据状态流转。
分页/增量模式：聚水潭侧多用 status+date_type 增量（如策略 17 用 status=Confirmed、date_type=2、7 天时间窗）；金蝶侧多用 FApproveDate 作为增量锚点，全量回填则依赖 LAST_SYNC_TIME 游标。
典型字段映射
| 字段名 | 类型 | 含义 | 实战注意事项 |
|---|---|---|---|
| FBillNo / io_id / as_id | String | 单据编号 | 两边系统都用其做幂等键，避免重复推送 |
| FStockId.FNumber ↔ wms_co_id | String | 仓库编码 | 必须建立仓库映射表；聚水潭分仓编号与金蝶仓位 FNumber 一一对应 |
| FSupplierId.FNumber ↔ supplier_id | String | 供应商编码 | 通常需联查扩展字段 F_QKMS_JSTBM 维护映射 |
| shop_id ↔ FCustomerID | String | 店铺编码转客户编码 | 聚水潭店铺为电商店铺，金蝶侧需建对应客户档案 |
| FMaterialId.FNumber ↔ sku_id | String | 物料/商品编码 | 这是两系统主数据桥梁，必须最先打通 |
| FQty / FGainQty / FLossQty | Decimal | 数量 | 盘盈用 FGainQty，盘亏用 FLossQty，容易混淆 |
| FTaxPrice / FPrice | Decimal | 单价 | 注意含税/不含税区分；聚水潭 amount 通常为含税合计 |
| FLot / FLot_FNumber | String | 批号 | 出入库与调拨均携带；日期格式需统一为 yyyy-MM-dd |
| F_QKMS_* | String | 金蝶自定义字段 | 电商专属字段（快递单号、付款时间等）通常挂在此命名空间 |
| io_date / pay_date / end_time | DateTime | 日期时间戳 | 金蝶侧需做日期格式转换；策略 18 用 end_time 更新确认收货日期 |
在轻易云上如何配置
轻易云数据集成平台对聚水潭与金蝶云星空的集成封装为两个标准化适配器：聚水潭适配器覆盖奇门与非奇门两套接口族（jushuitan.saleout.list.query、jushuitan.refund.list.query、/open/orders/out/simple/query 等），金蝶云星空适配器则按 FormId 提供物料、供应商、仓库、销售出库等模型。
在轻易云里，通常采用如下配置路径：
- 在「数据源」中注册两家系统的认证信息（聚水潭 AppKey/ShopId、金蝶帐套/第三方登录凭证）。
- 使用轻易云的字段映射器配置主表与明细行的字段对应关系，支持 DIRECT、CONSTANT、COLLECTION（联查映射表）、TRANSFORM（拼接/格式化）四种映射类型。
- 轻易云的调度编排器支持按策略类型设置执行频率，基础资料与业务单据分层调度；内置重试、失败队列与告警。
- 编码映射表（物料、客户、仓库、供应商）通过轻易云的映射表功能维护，新出现的未映射编码会自动触发告警。
跨方案实战要点
- 基础资料先行：物料、客户、仓库、供应商四大主数据必须在业务单据同步前完成；策略 2-7 的查询策略建议每 2 小时跑一次维护映射表。
- 单据类型常量与组织常量必须配置化：策略 17 的 FBillTypeID=XSCKD01_SYS、FSaleOrgId=101、FStockOrgId=100 这些常量在不同客户环境下可能不同，必须做成可配置参数。
- 奇门 vs 非奇门双轨并行：真实场景里电商渠道往往既有奇门接口也有非奇门接口，需要在策略层做分流（按 shop_id 或 order_type 路由），避免漏单。
- 京东退货走专用客户：策略 19 与策略 23 都要求 FRetcustId 固定为京东渠道专用客户编码，必须在映射表中维护京东渠道对应客户，否则退货无法正确入账。
- 确认收货日期更新依赖反向查询：策略 18 不能直接推送，需先调用策略 20 查询金蝶销售出库单，通过 FThirdBillNo=o_id 关联获得 FID 后再做 BatchSave。
- 时间窗不超过 7 天：聚水潭侧官方建议单次查询窗口不超过 7 天，避免漏单与超时；增量任务必须每天滚动推进。
踩坑复盘
-
FGainQty 与 FLossQty 混淆：盘盈单用 FGainQty、盘亏单用 FLossQty，这两个字段名相似但方向相反，配置时极易抄错；稳妥的做法是在轻易云映射器里通过 FBillTypeID 二次判断类型后再绑定数量字段。
-
金蝶组织/单据类型常量硬编码：FBillTypeID、FSaleOrgId 等常量的具体值在多客户环境下千差万别，硬编码后换客户就要改源码；稳妥的做法是抽到轻易云的全局变量或客户级配置表中。
-
聚水潭金额含税口径不一致：聚水潭 amount 默认含税合计，而金蝶 FTaxPrice 是含税单价，FAmount 是含税金额；如果直接拿 amount 写 FEntryTaxAmount 没问题，但若换成不含税就会差一截税额，财务对账时会暴露。
-
日期格式 7 天滑动窗漏单：增量任务以今天为结束时间倒推 7 天，若某天任务挂了，重启后会出现单据空档；稳妥做法是把结束时间钉死为上一次成功结束的时间戳，而不是当前时间。
-
编码未映射导致整批失败：映射表缺失某个 shop_id 或 sku_id 会导致整条单据卡住；务必在轻易云映射器里设置"编码缺失→写入失败队列+告警"而非抛错中断整批。
何时选用
适用于聚水潭电商业务与金蝶云星空财务/供应链并存的零售企业，需打通商品、采购、库存、销售、售后双向数据。边界在于：该方案仅做单据级同步，不涉及工作流审批流自动化；若客户要求两套系统共用一套审批流，应考虑更深的业务融合方案。