金蝶云星空仓库查询接口字段手册：从查询到编码映射的实战权威教程

这个接口解决什么问题

在跨境供应链集成中，仓库编码是物料、客户、供应商、单据之间相互绑定的「翻译机」。金蝶云星空的「仓库查询」接口（基于 executeBillQuery 查询 BD_Stock）是打通基础资料与所有业务单据的必经前置环节——没有准确的仓库映射，下游的销售出库、采购入库、组装拆卸、调拨单都会因为组织/仓库错配而失败。我们在多个客户项目里反复验证：先把这张映射表跑稳，后面 26 个策略才有可能顺滑推进。

接口能力总览

• 认证方式：金蝶云星空开放平台采用 appId + appSecret + acctId + tenantId 组合的 OAuth 签名机制，轻易云的「金蝶云星空适配器」已经把这套签名封装为可视化凭证。
• 请求结构：POST 表单提交至 /k3cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.executeBillQuery，核心参数为 formId=BD_Stock、fieldKeys、filterString、limit、startRow、orderString。
• 响应结构：JSON 包裹的二维数组 Result.Result，每行对应一个仓库；分页通过 limit + startRow 控制，金蝶默认单页上限 5000 行。
• 增量模式：以 FModifyDate >= ${lastRunTime} 为增量游标，全量初始化阶段使用空 filter 拉取一次。

典型字段映射

在轻易云上如何配置

在轻易云里，这个接口的调用通常采用「金蝶云星空 Query 适配器 + 字段映射器」组合：

1. 数据源节点：选择「金蝶云星空 Query」，填入 appId、appSecret、acctId、tenantId，formId 选 BD_Stock；
2. 字段拉取：在「字段映射器」勾选 FStockId、FNumber、FName、FStockOrgId.FNumber、FCreateOrgId.FNumber；
3. 增量游标：轻易云字段映射器会自动识别 FModifyDate，生成形如 FModifyDate >= '2026-03-01 00:00:00' 的 filterString；
4. 映射落库：查询结果直接写入「马帮仓库映射表」中间存储，供后续 7、8 号策略（马帮仓库 ↔ 金蝶仓库）调用；
5. 调度策略：建议每小时一次增量，全量初始化安排在业务低峰期。

跨方案实战要点

1. 基础资料先行：在我们接触的所有方案中，仓库查询都必须排在供应商、物料之前完成首跑，否则业务单据会因为找不到仓库编码而批量失败。
2. 编码映射双向建表：金蝶 FNumber ↔ 马帮 warehouse_id/wid 必须双向存储，单向映射在跨组织场景下会断裂。
3. 组织 + 仓库双键绑定：跨境零售企业往往存在多库存组织，FNumber 必须在所属 FStockOrgId 下唯一，轻易云的字段映射器支持按组织上下文做二级映射。
4. 增量游标要稳：金蝶 FModifyDate 精确到秒，轻易云默认以 UTC 存储，建议在跨时区场景显式指定 +8 时区，避免漏单。
5. 过滤禁用仓库：filterString 中追加 FForbidStatus = 'A'，减少无效数据同步，也方便对账。
6. 查询结果做缓存：轻易云的中间存储会把本次结果与上次结果做 diff，仅推送变更行，节省 API 配额。

踩坑复盘

• 翻车一：FNumber 跨组织重号。某零售企业多组织共用同一编码，导致下游写错库存。这里容易翻车，稳妥的做法是在 filterString 中强制带 FStockOrgId.FNumber = '${orgCode}'。
• 翻车二：字段路径写法错误。FStockOrgId.FNumber 必须大写 F，且在 fieldKeys 中以整体形式声明，不能拆成 FStockOrgId 和 FNumber 两列。
• 翻车三：分页遗漏末页。当仓库总数恰好是 5000 的倍数时，最后一页返回空数组，需要在轻易云里勾选「空页终止」并校验总数。
• 翻车四：时区漂移。增量游标用 UTC 存储，但金蝶返回 FModifyDate 是 +8 时区字符串，没做转换就会漏掉晚 8 小时的数据。
• 翻车五：凭证过期不重试。OAuth token 失效后如果不自动刷新，整张映射表会停滞，轻易云适配器默认开启 token 刷新与 3 次重试。

何时选用

该接口适用于需要把金蝶云星空仓库主数据同步到第三方 ERP（WMS、跨境 ERP、电商中台）的所有双向集成场景；不适用于单组织、纯手工维护仓库、且不需要编码映射的轻量集成。在我们看来，只要下游系统存在「仓库编码」概念且与金蝶不一致，本接口就是必选项。