金蝶云星空「网店-仓库映射」接口字段手册权威教程
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 * * *是某零售企业的常见节奏)。
典型字段映射
| 字段名 | 类型 | 含义 | 实战注意事项 |
|---|---|---|---|
| FID | string | 网店主表内键,金蝶内唯一标识一个网店 | 增量同步的主锚点之一 |
| FNumber | string | 网店业务编码 | 业务侧引用一律用 FNumber,不要被 metadata 中的 number=FName 误导 |
| FName | string | 网店显示名称 | 仅用于展示,不能做业务主键 |
| FSaleOrgId_FNumber | string | 对应销售组织编码 | 多组织场景下做数据隔离的关键 |
| FCustomerId_FNumber / FCustomerId_FName | string | 对应客户编码 / 名称 | 网店通常对应一个客户主体,用于应收、对账 |
| FStockOrgId_FNumber | string | 库存组织编码 | 决定库存可用量计算范围 |
| FShopStock_FEntryID | string | 店铺库存分录行主键 | 真正去重键;(FID, FShopStock_FEntryID) 才能唯一定位一条映射 |
| F_PBLH_WDTSTOCK_FNumber / _FName | string | 旺店通仓库编码 / 名称 | F_PBLH_ 是金蝶扩展字段前缀,表示对接旺店通的字段 |
| FStockId_FNumber / FStockId_FName | string | 金蝶仓库编码 / 名称 | 库存组织下的实际仓库,是订单与库存路由的终点 |
在轻易云上如何配置
- 金蝶适配器:轻易云内置金蝶云星空连接器,封装了
executeBillQuery的签名、租户切换、分页与错误重试,业务同学只需配置 FormId 与过滤条件。 - 字段映射器:把上表字段一次性映射到 MySQL
shop_warehouse_mapping表时,轻易云的字段映射器会自动把_FNumber/_FName拆成两列(编码列、名称列),无需手工 SQL 处理。 - 增量策略:用「修改时间 + 内键去重」组合键;轻易云的调度器内置「上次最大 FMODIFYDATE」缓存,直接勾选增量即可,断点也不会丢数据。
- 兜底:对每次批量结果落库前,建议开启轻易云的「空响应判定」,避免接口静默无数据时误判为成功。
跨方案实战要点
- 真正的去重键是
(FID, FShopStock_FEntryID):FID只是网店主表,一个网店有多条仓库映射,只用FID必然重复。 FNumber≠FName:金蝶响应 metadata 里number字段值其实是名称,这是真实场景里最容易翻车的地方,务必以「FNumber= 编码,FName= 名称」的规则自己建模。- 增量条件用
FMODIFYDATE>=:在多个客户的方案里我们都发现,直接用>在跨天边界会漏数据,稳妥写法是「上一次成功时间 - 2 分钟」+>=,并按FMODIFYDATE, FID排序。 F_PBLH_前缀是扩展字段:看到这种前缀不要当成系统标准字段,它通常由二开或对接方维护,变更频次高于基础资料,需要单独做变更监控。- 分页建议
Limit=2000:实测 5000 在大组织下偶发 OOM,2000 是性能与稳定性的甜点。 - 多组织下
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