这个接口解决什么问题

金蝶云星空的「即时库存查询」接口(FormId = STK_Inventory)是供应链集成中的高频入口。它把多组织、多仓库、多货主、多批次的库存账面量与可用量以统一结构吐出,供 MySQL 等业务库构建统一库存视图、做可用量查询、做库存对账与保质期预警。我们在多个客户项目里观察到:把这条接口接稳,后续 BI、ERP、WMS 协同的很多阻塞点都能提前消解。

接口能力总览

协议与认证:基于金蝶云星空开放平台,采用 executeBillQuery 查询型接口;常见为 AppSecret + 签名或 OAuth 风格的接入凭证(具体以租户侧开通为准),调用端需携带租户上下文与单据 FormId。
请求结构:核心入参包括 FormId、FilterString(增量过滤条件)、FieldKeys(要返回的字段)、Limit、StartRow,可选 TopRowCount 用来一次返回总数。
响应结构:返回 JSON 数组形式的明细行,每行内含字段键值;元数据(metadata)中 id 对应 FID,number 对应 FMaterialId_FNumber。
分页模式:基于 Limit + StartRow 的传统分页,TopRowCount 控制总行数返回;建议单页 2000~5000 行,过大容易触发接口侧超时。
增量模式:默认按 FUpdateTime 增量,过滤条件 FUpdateTime >= '{{LAST_SYNC_TIME|datetime}}' and FStockId.FNumber <>'不良品仓',默认 5 分钟轮询。

典型字段映射

字段名	类型	含义	实战注意事项
FID	string	库存记录主键	入库目标表的唯一键,metadata 中 `id` 即此字段
FStockId_FNumber	string	仓库编码	对接目标系统的仓库主数据
FMaterialId_FNumber	string	物料编码	跨系统对账的主键之一,务必使用 `_FNumber` 业务编码
FMaterialId_FName	string	物料名称	用于人工核对的展示字段
FBaseQty	string	基本单位库存量	注意单位换算,基本单位 ≠ 销售/采购单位
FBaseAVBQty	string	基本单位可用量	通常 = 库存量 − 占用/锁定量
FLot	string	批次号	启用批次管理的物料才有值
FUpdateTime	string	最后更新时间	增量字段,务必按时区统一处理
FOwnerId_FNumber	string	货主编码	多货主场景的关键维度
FKeeperId_FNumber	string	保管者编码	多保管者/委外场景用得到
FStockOrgId_FNumber	string	库存组织编码	多组织集团环境的必备维度
FStockStatusId	string	库存状态	良品/不良品/冻结等,影响是否纳入可用
FProduceDate / FExpiryDate	string	生产/有效期	保质期预警与 FIFO 的依据
FSpecification	string	规格型号	来自物料主数据,常用于展示
FMaterialId_FMaterialGroup	string	物料分组	用于按品类聚合统计

在轻易云上如何配置

在轻易云数据集成平台里,这个接口通常通过「金蝶云星空适配器」以可视化方式接入:选择 executeBillQuery,填入 FormId = STK_Inventory,把 FilterString 模板化后,平台会按计划自动注入上一次同步时间戳。轻易云的字段映射器会自动把 _FNumber 系列字段识别为业务编码,与目标 MySQL 表的 warehouse_code / material_code / lot_number 直接对接;对 FBaseQty / FBaseAVBQty,平台会提示单位字段并支持内置的单位换算脚本钩子,避免在 SQL 层硬处理。

跨方案实战要点

编码字段优先于内键:FMaterialId_FNumber、FStockId_FNumber、FOwnerId_FNumber 这类 _FNumber 系列才是跨系统对账的主键,内键 FMaterialId 仅用于回查金蝶元数据,入库时不要混用。
组合维度决定唯一性:一行库存由「库存组织 + 仓库 + 物料 + 批次 + 货主 + 库位 + 库存状态」共同决定,目标表主键应按这套组合维度设计,否则会丢数据或产生重复行。
增量用 FUpdateTime,全量用 FID:增量同步必须依赖 FUpdateTime,且要与金蝶服务器时区对齐;首次全量则按 FID 分页更稳。
默认过滤不良品仓:FilterString 里把 FStockId.FNumber <>'不良品仓' 作为基础项,避免把异常仓的库存污染到可用量计算里。
可用量 ≠ 库存量:BI 端做「可售」「可发」口径时,务必用 FBaseAVBQty,而 FBaseQty 只反映账面。
批次/有效期是高频扩展维度:做保质期预警、FIFO 时,FLot / FProduceDate / FExpiryDate 三件套务必入库,后期改表成本极高。

踩坑复盘

「数据明明有,接口却返回空」:通常是 FilterString 拼接错了时间格式;稳妥的做法是先用 TopRowCount 不带条件确认接口通,再加时间过滤。
「同一物料库存翻倍」:内键与业务编码混用,主键里既写了 FMaterialId 又写了 FMaterialId_FNumber 但取值来源不一致。统一用 _FNumber 作为业务键即可。
「可用量对不上账」:把 FBaseQty 当可用量用,忽略了 FBaseAVBQty 才扣减了占用/锁定;或者忘了过滤不良品仓与冻结状态。
「增量漏数据」:FUpdateTime 时区不一致,金蝶侧是带时区字符串,直接当本地时间比较会造成边界行漏取。建议在源头就做时区归一。
「分页越拉越慢」:单页 Limit 过大导致接口超时;把 Limit 调到 2000~5000,并用 TopRowCount 只在首次拉一次总数即可。

何时选用

只要业务上需要从金蝶云星空拿到「当前时点」的库存账面量与可用量,并与外部系统(MySQL、BI、WMS)做对账或同步,就可以选这条接口。如果诉求是出入库事务流或单据级联,应转向单据保存/审核接口;它不适合做事务回放。

金蝶云星空即时库存查询接口字段手册权威教程