金蝶云星空库存余额(executeBillQuery)接口字段手册权威教程——线上仓库存查询实战

这个接口解决什么问题

在某零售企业的电商业务里,线上仓库存需要在金蝶云星空与前端电商平台之间高频同步:聚水潭要拉取可售库存用于下单锁库,运营要对账、要监控临期批次。该接口(executeBillQuery 查询 STK_Inventory)只取线上拣货可用仓库的库存余额,按 FUpdateTime 增量返回,是电商仓可用库存同步与对账场景的核心入口。

接口能力总览

• 认证方式:金蝶云星空私有化部署下的用户/应用鉴权,需在请求头携带会话凭证;在轻易云里通常封装为适配器的「连接信息」,由平台托管刷新。
• 请求结构:POST /executeBillQuery,Form 字段固定 STK_Inventory,支持 FID/FStockId/FMaterialId/FBaseQty/FBaseAVBQty/FLot/FUpdateTime 等可选字段筛选;另支持 FilterString(组合 SQL 风格过滤)、Limit(默认 20)、StartRow(默认 0)。
• 响应结构:返回二维结果集,首行为字段名,数据行从第二行起;metadata 中 id=FID、number=FMaterialId_FNumber。
• 分页模式:Limit + StartRow 翻页;本策略每 5 分钟(7:00–23:59)增量拉取,FilterString 自动替换 {{LAST_SYNC_TIME|datetime}},由轻易云调度器持久化游标。
• 写入策略:Target 端配置为空操作,本策略为纯查询,仅落轻易云数据中台供下游订阅。

典型字段映射

在轻易云上如何配置

• 数据源适配器:选「金蝶云星空-查询」类型,填入私有化地址、账套与认证信息;轻易云会自动封装 executeBillQuery 调用。
• 业务对象选择:STK_Inventory,平台会拉取字段元数据并预填主键与编码。
• 过滤模板:FilterString 直接配置 FUpdateTime >= '{{LAST_SYNC_TIME|datetime}}' and FStockId.F_POKM_onlinepicking ='1',轻易云的占位符会在每次调度时由调度器替换。
• 字段映射器:把 _FNumber 系列映射到下游业务编码;FBaseQty/FBaseAVBQty 用 to_number() 表达式转数值;时间字段用 parse_datetime() 标准化。
• 目标端:配置「空操作」,查询结果落到轻易云中台,供销售出库、可售同步、对账等下游订阅。
• 调度:3-59/5 7-23 * * *,轻易云调度中心会自动管理游标持久化与失败重试。

跨方案实战要点

1. 线上仓 vs 线下拣货仓的过滤:金蝶通过 FStockId.F_POKM_onlinepicking='1' 区分线上仓,这是电商业务的关键;切勿漏写,否则会拉回线下仓库存污染可售。
2. 可售 ≠ 账面:务必映射 FBaseAVBQty,不要用 FBaseQty 同步可售,否则会出现超卖。
3. 字符串数字要转:金蝶返回的数量都是 string,轻易云字段映射器里要加显式转换,否则下游会出现 100 vs 100.0 的比对异常。
4. 增量游标管理:FUpdateTime 是字符串,跨天/跨时区要测试一致性;多个仓库、多组织场景需把 FStockOrgId_FNumber 也带进过滤。
5. 批次与库位是空值常态:FLot、FStockLocId02~08 在未启用批次或多级库位时为 null,下游写入要做空值兜底,不要把 null 当空串处理。
6. 状态码过滤:FStockStatusId 不等于「可用」的记录(冻结、待检)在可售同步里必须剔除,稳妥做法是在映射器里写条件表达式二次过滤。

踩坑复盘

1. 漏写 F_POKM_onlinepicking 过滤:某客户首次上线没加线上仓过滤,把线下批发仓库存也同步到了电商前端,导致大面积超卖;修复:FilterString 强制带上该条件,并在轻易云里加单元测试断言。
2. 增量重复拉取:FUpdateTime 为字符串时,>= 比较在某些数据库实现里大小写敏感;稳妥的做法是在轻易云字段映射器里统一转大写并用 >= 精确时间戳。
3. _FNumber 与 _FName 错配:有工程师把 FNumber(编码)与 FName(名称)混用,导致仓库/物料对账时显示为名称而非编码;务必在映射器里固定选 *_FNumber。
4. 数量字段当字符串累加:聚水潭下游做库存汇总时,因为金蝶返回的是 "100.00",直接相加会出现字符串拼接而非求和;映射器必须转数值类型。
5. 库位层级数错位:金蝶支持多级库位,客户系统只用到 3 级,却把所有 FStockLocId02~08 都当成必填,导致非空校验失败;实际应按客户主数据配置启用层级处理。

何时选用

当你需要从金蝶云星空高频拉取线上电商仓的可售/账面库存并对外(电商平台、WMS、对账系统)分发时,executeBillQuery + STK_Inventory 是最稳的入口;若涉及库存写入或事务冻结,需切换到保存类 API,纯查询策略不适用。