金蝶云星空仓库查询接口（BD_STOCK）字段手册与实战教程

这个接口解决什么问题

在旺店通与金蝶云星空的供应链集成里,仓库主数据是所有出入库单、调拨单、销售订单的「地基字段」。一旦两端仓库编码对不上,下游单据要么推不过去,要么推到错误的实体仓。该接口通过 executeBillQuery 直接读取金蝶侧的仓库基础资料(含自定义的旺店通映射字段),用于建立跨系统仓库主数据映射,为后续单据同步提供可信的仓库字典。

接口能力总览

• 认证方式:金蝶云星空标准的 OAuth/Token 认证,在轻易云里通过金蝶适配器统一托管。
• 请求接口:executeBillQuery,表单 ID 为 BD_STOCK(仓库基础资料)。
• 请求结构:支持 FilterString(金蝶过滤语法)、Limit、StartRow、TopRowCount 分页参数。
• 响应结构:标准列表型 JSON,字段均以 F 前缀返回,关联字段(如使用组织)以 FUseOrgId.FNumber 这种嵌套形式返回。
• 分页模式:传统 Limit/StartRow 分页;真实场景中,仓库主数据量通常在几百到几千条,一次性拉完也常见,但稳妥做法仍走分页。
• 增量模式:基于 FModifyDate>='{{LAST_SYNC_TIME|datetime}}' 配合 FUseOrgId.FNumber='106' 这类组织过滤,定时任务 */10 * * * * 每 10 分钟一轮,是我们在多个客户项目里验证过的稳定模式。
• 策略性质:Target 配置为「写入空操作」,属于纯查询策略,不回写目标系统,只做主数据字典沉淀。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里,这个接口的调用通常采用「金蝶云星空查询适配器」+「字段映射器」的组合:

1. 适配器选择:选「金蝶云星空」适配器,接口动作选 executeBillQuery,FormId 填 BD_STOCK。
2. 过滤条件:FilterString 默认模板 FUseOrgId.FNumber='{{ORG_CODE}}' and FModifyDate>='{{LAST_SYNC_TIME|datetime}}',轻易云的变量占位符会自动替换最近同步时间。
3. 字段映射器:轻易云的字段映射器会自动把 FUseOrgId.FNumber 展开为 FUseOrgId__FNumber 这类扁平字段,方便后续写主数据映射表。
4. 调度:定时任务 */10 * * * * 即可,轻易云调度器会按增量时间窗逐步推进。
5. 目标端:由于是纯查询,Target 选「空操作(写入空操作)」,只把结果落到轻易云的中间表,供后续单据策略(如销售出库单)查表引用。

跨方案实战要点

1. 「关联查询」策略一定是字典型策略:它本身不写数据,目的是为下游所有带仓库字段的单据提供「金蝶仓库 ↔ 旺店通仓库」映射底表。
2. FUseOrgId 过滤不可省:金蝶是多组织架构,不指定组织会拉到全集团仓库,映射表里就会出现一堆无关仓库,排查时极易翻车。
3. F_KD_WDTSTOCK 是金-旺映射的「准绳」:在多套客户方案里,只要这字段为空,基本就是实施方没在金蝶侧给仓库打自定义字段,需要在金蝶里补字段映射。
4. FModifyDate 增量字段要校验有效性:我们曾在某零售企业遇到过 FModifyDate 不更新(只创建时写一次)的怪异情况,最后退化到全量比对兜底。
5. 仓库编码作为匹配键更稳:FNumber 比 FName 更适合做匹配键,名称重复或被改名的概率远高于编码变更。
6. Target 留空是合规设计:别顺手给加一个写入目标,字典型查询若被误写回目标系统,容易把别人的仓库主数据覆盖。

踩坑复盘

• 坑 1:FUseOrgId 忘了带过滤。拉到全集团仓库,映射表里出现一堆测试组织,下游单据全部映射失败。应对:FilterString 强制带上 FUseOrgId.FNumber='{{ORG_CODE}}',在轻易云里把它写进默认模板,禁止裸跑。
• 坑 2:FStockId 当成业务编码用。FStockId 是金蝶内部主键(GUID),会随数据迁移或重新导入变化。应对:映射表主键用 FNumber,FStockId 只做内部去重。
• 坑 3:F_KD_WDTSTOCK 为空还以为没数据。仓库在金蝶侧确实存在,但实施方没补这个自定义字段。应对:先在金蝶端核对字段是否已加、是否已维护值,再排查接口问题。
• 坑 4:分页参数 TopRowCount 设太大被金蝶截断。金蝶对单次返回行数有限制(常见 5000),超过会被截断且不报错。应对:稳妥的做法是 Limit 设 2000,显式分页并核对总条数。
• 坑 5:增量时间戳跨时区漂移。金蝶服务器时区与轻易云调度器时区不一致时,会出现「刚刚改的仓库拉不到」或「重复拉到旧数据」。应对:在轻易云的调度配置里显式锁定时区(通常 UTC+8),FilterString 的时间变量也带时区后缀。

何时选用

当你需要做旺店通↔金蝶云星空的供应链集成、且业务单据(如销售出库、调拨单)依赖两端仓库编码映射时,就该把这个「关联查询」策略跑起来。它只解决一件事:沉淀一份干净、增量、带组织维度的仓库主数据字典,供所有下游策略复用。单据级同步、出入库校验等场景,建议先建好这份底表,再谈下游。