What problem this API solves

The "Instant Inventory Query" API of Kingdee Cloud (FormId = STK_Inventory) is a high-frequency entry point in supply chain integration. It exposes unified structure for inventory quantities and available quantities across multi-org, multi-warehouse, multi-owner, and multi-batch dimensions, enabling downstream MySQL or BI systems to build unified inventory views, query availability, perform reconciliation, and run shelf-life alerts. In our experience across multiple customer projects, getting this API stable up front clears many later BI/ERP/WMS collaboration blockers.

API capability overview

Protocol & auth: Built on Kingdee Cloud's open platform using executeBillQuery; typically AppSecret + signature or OAuth-style credentials (depending on tenant provisioning). The caller must include tenant context and the bill FormId.
Request structure: Core params include FormId, FilterString (incremental condition), FieldKeys (fields to return), Limit, StartRow, and optional TopRowCount for total row counts.
Response structure: Returns a JSON array of detail rows; metadata's id maps to FID, number maps to FMaterialId_FNumber.
Pagination: Classic Limit + StartRow pagination; TopRowCount controls whether a total is returned. Page size of 2000–5000 rows is recommended; larger pages risk server-side timeouts.
Incremental pattern: Default by FUpdateTime; condition FUpdateTime >= '{{LAST_SYNC_TIME|datetime}}' and FStockId.FNumber <>'不良品仓'; default polling every 5 minutes.

Typical field mappings

Field	Type	Meaning	Practical notes
FID	string	Inventory record PK	Target table unique key; `id` in metadata
FStockId_FNumber	string	Warehouse code	Reconcile with target warehouse master data
FMaterialId_FNumber	string	Material code	Use `_FNumber` business code for cross-system reconciliation
FMaterialId_FName	string	Material name	Display field for manual verification
FBaseQty	string	Base-unit qty on hand	Base unit ≠ sales/purchase unit — apply UoM conversion
FBaseAVBQty	string	Base-unit available qty	Generally on-hand minus reserved/locked
FLot	string	Lot number	Only populated for batch-managed items
FUpdateTime	string	Last update time	Incremental field; normalize timezone carefully
FOwnerId_FNumber	string	Owner code	Key dimension in multi-owner scenarios
FKeeperId_FNumber	string	Keeper code	Needed for multi-keeper/subcontracting scenarios
FStockOrgId_FNumber	string	Stock org code	Required in multi-org groups
FStockStatusId	string	Stock status	Good/Defective/Frozen etc., affects availability
FProduceDate / FExpiryDate	string	Produce/Expiry date	Basis for shelf-life alerts and FIFO
FSpecification	string	Specification	Comes from material master, used for display
FMaterialId_FMaterialGroup	string	Material group	Used for category-level aggregation

How to configure it on Qeasy Cloud

On the Qeasy Cloud data integration platform, this API is normally wired up through the Kingdee Cloud adapter: pick executeBillQuery, set FormId = STK_Inventory, template the FilterString, and the platform will inject the last sync timestamp automatically on each scheduled run. The field mapper in Qeasy Cloud automatically recognises _FNumber series fields as business codes and maps them directly to warehouse_code / material_code / lot_number in the target MySQL table. For FBaseQty / FBaseAVBQty, the platform prompts for the unit field and exposes a unit-conversion script hook so you don't have to hardcode conversions in SQL.

Cross-scenario practical points

Business codes before inner keys: FMaterialId_FNumber, FStockId_FNumber, FOwnerId_FNumber etc. are the real cross-system reconciliation keys; the F*Id inner keys should only be used for looking up Kingdee metadata.
Uniqueness is composite: One inventory row is identified by the combination of "stock org + warehouse + material + lot + owner + stock loc + stock status". Design the target PK accordingly to avoid duplicates or data loss.
FUpdateTime for incremental, FID for full: Incremental sync must rely on FUpdateTime, aligned to Kingdee's timezone; for the initial full load, paginate by FID for stability.
Filter defective warehouse by default: Keep FStockId.FNumber <>'不良品仓' in FilterString as a baseline to prevent abnormal warehouse stock from polluting availability calculations.
Available ≠ on-hand: For "sellable" or "shippable" KPIs in BI, always use FBaseAVBQty; FBaseQty is only the book balance.
Batch/expiry is a frequent must-have: For shelf-life alerts and FIFO, ensure FLot / FProduceDate / FExpiryDate are all persisted; retrofitting later is expensive.

Pitfalls and fixes

"Data exists but API returns empty": usually a wrong datetime format in FilterString. The safe approach is to first call with TopRowCount and no condition, then add the time filter.
"Same material's stock doubled": mixing inner keys and business codes as PK sources. Standardise on _FNumber business keys.
"Available quantity doesn't reconcile": using FBaseQty as available qty, ignoring that FBaseAVBQty already deducts reserved/locked; or forgetting to filter defective warehouses and frozen statuses.
"Incremental misses rows": timezone mismatch on FUpdateTime. Kingdee returns timezone-aware strings; comparing them as local times causes boundary losses. Normalize the timezone at the source.
"Pagination gets slower each round": page Limit too large triggers server timeouts. Drop Limit to 2000–5000 and use TopRowCount only on the first round.

When to use it

Use this API whenever you need to pull current-snapshot book balances and available quantities from Kingdee Cloud and sync them to external systems (MySQL, BI, WMS) for reconciliation or unification. For transactional flows or bill-level linkage, switch to the bill save/audit APIs; this API is not designed for transaction replay.

Authoritative Tutorial: Kingdee Cloud Instant Inventory Query API Field Handbook