轻易云
注册体验

金蝶云星空「网店-仓库映射」接口字段手册权威教程

· 陈洁琳· 工程最佳实践· 23 次浏览· 约 4 分钟读完
MySQL金蝶云星空executeBillQuery网店仓库映射供应链集成字段手册轻易云

这个接口解决什么问题

在零售与电商供应链集成里,「网店 ↔ 仓库」的映射关系是订单、库存和发货的根基。多家客户的实践都指向同一个痛点:金蝶侧有完整的主数据,但下游电商平台(典型如旺店通)的仓库编码需要与金蝶仓库一一对应,才能把订单和库存正确路由。该接口以 executeBillQuery 方式拉取网店主数据及其与金蝶仓库、旺店通仓库的映射明细,作为后续订单、库存、出入库集成的配置底座。

接口能力总览

  • 接口形态:金蝶云星空通用查询接口 executeBillQuery,业务对象 FormId 为 ECC_Shop(网店管理单据)。
  • 认证方式:金蝶云星空标准身份认证(应用 ID / 安全密钥 / 用户授权),轻易云通过金蝶适配器统一托管签名与会话。
  • 请求结构:FormId=ECC_Shop + FieldKeys(字段列表) + FilterString(过滤条件,常用 FMODIFYDATE>='2024-01-01 00:00:00' 做增量) + StartRow / Limit(分页) + OrderString。
  • 响应结构:每条记录是一个 Map,key 为字段名(含 _FNumber / _FName / _FEntryID 这种关联字段后缀),外层 metadata 中 id 对应主键。
  • 分页与增量:典型分页 Limit=1000~2000,按 FMODIFYDATE 递增;生产环境建议每 5 分钟一次,在业务高峰前完成一轮抓取(crontab */5 7-22 * * * 是某零售企业的常见节奏)。

典型字段映射

字段名类型含义实战注意事项
FIDstring网店主表内键,金蝶内唯一标识一个网店增量同步的主锚点之一
FNumberstring网店业务编码业务侧引用一律用 FNumber,不要被 metadata 中的 number=FName 误导
FNamestring网店显示名称仅用于展示,不能做业务主键
FSaleOrgId_FNumberstring对应销售组织编码多组织场景下做数据隔离的关键
FCustomerId_FNumber / FCustomerId_FNamestring对应客户编码 / 名称网店通常对应一个客户主体,用于应收、对账
FStockOrgId_FNumberstring库存组织编码决定库存可用量计算范围
FShopStock_FEntryIDstring店铺库存分录行主键真正去重键;(FID, FShopStock_FEntryID) 才能唯一定位一条映射
F_PBLH_WDTSTOCK_FNumber / _FNamestring旺店通仓库编码 / 名称F_PBLH_ 是金蝶扩展字段前缀,表示对接旺店通的字段
FStockId_FNumber / FStockId_FNamestring金蝶仓库编码 / 名称库存组织下的实际仓库,是订单与库存路由的终点

在轻易云上如何配置

  • 金蝶适配器:轻易云内置金蝶云星空连接器,封装了 executeBillQuery 的签名、租户切换、分页与错误重试,业务同学只需配置 FormId 与过滤条件。
  • 字段映射器:把上表字段一次性映射到 MySQL shop_warehouse_mapping 表时,轻易云的字段映射器会自动把 _FNumber / _FName 拆成两列(编码列、名称列),无需手工 SQL 处理。
  • 增量策略:用「修改时间 + 内键去重」组合键;轻易云的调度器内置「上次最大 FMODIFYDATE」缓存,直接勾选增量即可,断点也不会丢数据。
  • 兜底:对每次批量结果落库前,建议开启轻易云的「空响应判定」,避免接口静默无数据时误判为成功。

跨方案实战要点

  1. 真正的去重键是 (FID, FShopStock_FEntryID):FID 只是网店主表,一个网店有多条仓库映射,只用 FID 必然重复。
  2. FNumber ≠ FName:金蝶响应 metadata 里 number 字段值其实是名称,这是真实场景里最容易翻车的地方,务必以「FNumber = 编码,FName = 名称」的规则自己建模。
  3. 增量条件用 FMODIFYDATE>=:在多个客户的方案里我们都发现,直接用 > 在跨天边界会漏数据,稳妥写法是「上一次成功时间 - 2 分钟」+ >=,并按 FMODIFYDATE, FID 排序。
  4. F_PBLH_ 前缀是扩展字段:看到这种前缀不要当成系统标准字段,它通常由二开或对接方维护,变更频次高于基础资料,需要单独做变更监控。
  5. 分页建议 Limit=2000:实测 5000 在大组织下偶发 OOM,2000 是性能与稳定性的甜点。
  6. 多组织下 FSaleOrgId 必带:不做销售组织过滤,会把所有组织的网店全部拉回来,做集团报表时容易踩合规坑。

踩坑复盘

  • 坑 1:把 FName 当编码入业务库。某零售企业第一版用 metadata.number 同步,结果编码列里全是名称,下游订单路由全部失败。应对:显式以 FNumber 为编码列,并加唯一约束。
  • 坑 2:增量漏数据。只按 FMODIFYDATE > 当前时间 查询,跨分钟边界时同一秒内的多条记录会漏。应对:退化为 >= + 向前回拨 2 分钟 + 按 FMODIFYDATE, FID 排序去重。
  • 坑 3:仓库映射一对多被压平。把分录数据直接拍平成一列 JSON 存库,后续做库存分配时性能极差。应对:在 MySQL 侧建明细表 (FID, FShopStock_FEntryID) 唯一索引,保持行式存储。
  • 坑 4:旺店通仓库编码被修改。F_PBLH_WDTSTOCK_FNumber 在旺店通侧改后,金蝶历史订单里的引用就失效了。应对:在落库时同时保留「映射编码」与「映射名称」两份,并对名称做模糊匹配日志告警。
  • 坑 5:调度粒度过细打挂金蝶。每 30 秒跑一次导致金蝶接口被限流。应对:拉到 */5 7-22 * * *,并轻易云侧配置并发限流。

何时选用

只要你的业务存在「电商平台店铺 ↔ ERP 仓库」的映射需求,需要为订单、库存、发货提供路由配置,就应该选用本接口。单店单仓或仓库完全独立的新建业务可不必引入;一旦涉及多平台、多店铺、多仓库的存量梳理,该接口是整个供应链集成链路的「地基查询」,建议优先落地。

本文为原创内容,转载请注明出处:https://www.qeasy.cloud/insights/engineering/hb-p2-017-9e15

评论