旺店通与金蝶云星空供应链集成:跨方案接口字段手册权威教程
这个接口解决什么问题
电商 OMS/WMS(旺店通)与 ERP(金蝶云星空)之间存在天然的数据孤岛:物料档案、库存变动、销售出退货、采购收退货在两边各自沉淀,口径不一致导致对账困难、库存漂移、采购与发货脱节。本文聚焦这两套系统的全链路集成,把基础资料、库存、销售、采购、退货五大域的 27 个策略聚合成一份实战手册,让工程师一次掌握所有接口的字段含义、映射逻辑与踩坑要点。
接口能力总览
认证方式:旺店通采用应用级 appkey + sid 签名机制;金蝶云星空私有化部署通常采用账套用户名密码 + 接口密钥,部分场景需绑定 IP 白名单。
请求/响应结构:旺店通开放平台以 JSON-RPC 风格封装,响应统一返回 code/status/message/data 四段式;金蝶云星空基于自研表单模型,主表与明细行(FEntity)分两层组织,FormId(如 SAL_OUTSTOCK、STK_TransferDirect)决定目标单据类型。
分页与增量模式:旺店通类接口普遍支持 page_no/page_size 分页,部分接口(如物料、调拨)支持按 start_time/end_time 时间窗增量;金蝶云星空建议以 FMODIFYDATE 作为增量游标,首次部署跑全量,之后跑增量。
典型字段映射
| 源字段(示例) | 目标字段(示例) | 类型 | 含义 | 实战注意事项 |
|---|---|---|---|---|
| 金蝶 FNumber | 旺店通 goods_no / spec_no | string | 物料/规格编码 | 编码映射表是所有下游策略的根基,务必先于业务单据同步 |
| 金蝶 FName | 旺店通 goods_name / spec_name | string | 名称 | 多语言/特殊字符需做转义,避免写入失败 |
| 金蝶 FBARCODE | 旺店通 barcode | string | 条码 | 一货多码场景建议按 spec_no 拆行 |
| 旺店通 order_no | 金蝶 FBillNo | string | 单据编号 | 金蝶对编号长度与前缀有规则,直接 1:1 写入可能触发校验 |
| 旺店通 consign_time / stockin_time | 金蝶 FDate | datetime | 业务日期 | 注意时区(UTC+8)与字符串格式转换 |
| 旺店通 warehouse_no | 金蝶 FStockOrgId / FStockId | string | 仓库/组织 | 金蝶仓库与组织是两层概念,组织映射不可漏配 |
| 旺店通 shop_no | 金蝶 FSaleOrgId / FCustomerID | string | 店铺/客户 | B 场景与 E(供销平台)场景映射规则不同,需分支处理 |
| 旺店通 provider_no | 金蝶 FSupplierId.FNumber | string | 供应商 | 供应商档案需先期同步,否则写入会被驳回 |
| 旺店通 spec_no / goods_no | 金蝶 FMaterialId.FNumber | string | 物料 | 明细行必须按 spec 维度展开,否则数量汇总错位 |
| 旺店通 num / goods_count | 金蝶 FQty / FRealQty | decimal | 数量 | 保留小数位与基本单位一致,严禁直接传件数 |
| 旺店通 sell_price | 金蝶 FPrice | decimal | 单价 | 注意精度与税率字段,部分场景需含税/不含税拆分 |
| 旺店通 logistics_no | 金蝶 FCARRIAGENO / F_ZZZZ_WLDH | string | 物流单号 | 退货单通常用自定义字段 F_ZZZZ_ 前缀 |
在轻易云上如何配置
在轻易云数据集成平台里,这套双系统集成通常被拆成适配器 + 策略编排两层。旺店通侧使用平台内置的「旺店通开放平台适配器」,只需配置 appkey/sid 与沙箱/生产环境即可;金蝶侧使用「金蝶云星空 WebAPI 适配器」,填入账套地址、用户、密钥并选择目标 FormId。
轻易云的字段映射器会自动识别两侧 Schema,把物料、客户、仓库、供应商的编码映射做成可视化配置表;对于策略 6/7(A/C 渠道)与 13/14(B 渠道)、16/17(E 渠道)这种「同表单多过滤条件」的策略,建议使用平台的策略克隆 + 过滤条件覆盖能力,而不是复制整个数据流。增量游标(FMODIFYDATE / consign_time)在轻易云的调度器里可直接配置为「按字段递增抓取」,并与告警策略(策略 11)联动,失败自动推送企业微信/钉钉。
跨方案实战要点
- 基础资料先行:物料、客户、供应商、仓库的编码映射表必须在所有业务单据之前跑通,否则后续 26 个策略都会因找不到 FMaterialId 而失败。
- 调拨双向对称:旺店通的调拨出/入库对应金蝶分步式调出/调入(策略 2/3);反向金蝶调入/调出则映射为旺店通「其他入库/出库」业务单(策略 4/5),两边不要混用单据类型。
- 同一出库单走不同渠道:旺店通同一张销售出库单,可能同时走 A(OMS 对账)、C(OMS 寄售)、B(不对账)、E(供销平台)四种下游,字段映射基本一致,关键差异在
shop_no → FSaleOrgId/FCustomerID的映射表与 FBillTypeID 常量。 - 采购链路强依赖:金蝶收料通知单先于采购单(策略 18),采购入库单必须携带
purchase_no反查上游(策略 19),否则无法过账。 - 增量游标双写:旺店通用
consign_time,金蝶用FMODIFYDATE,两边增量时间窗必须留 5-10 分钟缓冲,防止边界漏单。 - 编码映射可缓存:在轻易云里把物料、仓库、供应商的映射关系做成维度缓存表,单据写入前先做一次本地 join,既快又能提前拦截未知编码。
踩坑复盘
- 翻车 1:物料编码 1:1 直接写入,金蝶 FBillNo 长度超限。金蝶对单据编号有最大长度与前缀规则,旺店通原始 order_no 直接写入会被驳回。稳妥做法是在轻易云的字段映射器里加一个
SUBSTRING转换函数,并配置缺省前缀。 - 翻车 2:仓库与组织混淆。金蝶的 FStockOrgId(组织)与 FStockId(仓库)是两层,真实场景里我们见过客户把 warehouse_no 直接映射到 FStockOrgId,导致调拨单找不到组织维度。正确做法是分别建两张映射表。
- 翻车 3:销售退货单关联原始订单失败。金蝶退货单通常需要关联原销售出库单,旺店通 trade_no_list 是多值字符串,直接写入会报错。这里要善用轻易云的字符串处理函数(LEFT 40)截断并写入自定义字段 F_ZZZZ_DDBH。
- 翻车 4:增量丢单。只按
consign_time增量,跨天数据被切到下一天,导致当晚数据漏抓。稳妥做法是采用consign_time + 5 分钟滑动窗口,并以单据编号做幂等去重。 - 翻车 5:采购入库单无源单关联。旺店通采购入库单若未携带 purchase_no,金蝶会因无法关联上游采购订单而拒绝过账。务必在策略里把 purchase_no 作为联查键写入明细行。
何时选用
适用于中大型零售/电商企业,需要把旺店通(OMS/WMS)与金蝶云星空(ERP)做全链路供应链拉通,场景涵盖物料同步、库存对账、销售出退货、采购收退货。不适用于纯线下 ERP、纯财务对账,或仅做单点查询(如只查库存)的小型集成。
何时选用 (En)
Suitable for mid-to-large retail/e-commerce enterprises requiring full-chain supply chain integration between Wangdiantong (OMS/WMS) and Kingdee Cloud Cosmic (ERP), covering master data, inventory reconciliation, sales outbound/return, and purchase receiving/return. Not for pure offline ERP, pure financial reconciliation, or simple point-query integrations.