Authoritative Tutorial on Kingdee Cloud Inventory Balance (executeBillQuery) Interface Field Handbook — Online Warehouse Inventory Query in Practice

What This Interface Solves

In a retailer's e-commerce operation, online-warehouse inventory must be synchronized at high frequency between Kingdee Cloud and the storefront platform: the order system pulls sellable stock for allocation, operations reconciles balances, and the business monitors near-expiry batches. This interface (executeBillQuery against STK_Inventory) returns only the online-picking-enabled warehouses' inventory balances incrementally by FUpdateTime, and serves as the core entry point for online-warehouse sellable sync and reconciliation.

Capability Overview

• Authentication: User/application auth under a private deployment of Kingdee Cloud; session credentials are carried in request headers. In Qeasy Cloud, this is typically wrapped inside the adapter's "Connection" panel, with the platform handling token refresh.
• Request structure: POST /executeBillQuery, with the Form field fixed at STK_Inventory. Optional field filters include FID, FStockId, FMaterialId, FBaseQty, FBaseAVBQty, FLot, FUpdateTime. Also supports FilterString (SQL-style composite), Limit (default 20), and StartRow (default 0).
• Response structure: A two-dimensional result set whose first row is the field name and whose subsequent rows are data. In metadata, id=FID and number=FMaterialId_FNumber.
• Pagination mode: Limit + StartRow paging. This strategy pulls incrementally every five minutes (07:00–23:59), with FilterString automatically substituting {{LAST_SYNC_TIME|datetime}}; Qeasy Cloud's scheduler persists the cursor.
• Write strategy: The Target side is configured as a no-op, so this is a query-only strategy whose results are dropped into the Qeasy Cloud data middle layer for downstream subscription.

Typical Field Mapping

How to Configure on Qeasy Cloud

• Source adapter: Select the "Kingdee Cloud - Query" type, fill in the private-deployment address, account set, and authentication. Qeasy Cloud wraps the executeBillQuery call automatically.
• Business object: STK_Inventory; the platform fetches field metadata and prefills the primary key and number.
• Filter template: Set FilterString to FUpdateTime >= '{{LAST_SYNC_TIME|datetime}}' and FStockId.F_POKM_onlinepicking ='1'; Qeasy Cloud substitutes placeholders at every dispatch.
• Field mapper: Map the _FNumber series to downstream business codes. Convert FBaseQty / FBaseAVBQty with to_number(). Normalize datetime fields with parse_datetime().
• Target side: Configure a no-op; the query result lands in the Qeasy Cloud middle layer for downstream subscribers (sales-outbound, sellable sync, reconciliation).
• Scheduling: 3-59/5 7-23 * * *; Qeasy Cloud's scheduler manages cursor persistence and retries automatically.

Cross-Scenario Practical Points

1. Online-warehouse vs offline-picking filter: Kingdee uses FStockId.F_POKM_onlinepicking='1' to mark online warehouses; this is critical for e-commerce. Forgetting it pulls offline stock into the storefront and causes overselling.
2. Sellable ≠ on-book: Always map FBaseAVBQty, never FBaseQty, when syncing sellable stock.
3. String numerics need casting: All quantities come back as strings. Without an explicit cast in the mapper, downstream comparisons break ("100" vs 100.0).
4. Incremental cursor management: FUpdateTime is a string, and >= comparisons can be case-sensitive in some databases. A robust pattern is uppercase normalization plus an exact timestamp.
5. Lots and locations are routinely null: FLot and FStockLocId02~08 are null when batch management or multi-level locations are disabled. Downstream writes must null-coalesce; do not treat null as empty string.
6. Status-code filtering: Rows whose FStockStatusId is not "Available" (frozen, QA) must be excluded from sellable sync. The safe approach is a conditional-expression second filter inside the mapper.

Pitfalls and Fixes

1. Missing F_POKM_onlinepicking filter: In one customer rollout the team forgot the online-warehouse filter and synced offline wholesale stock into the e-commerce front end, triggering large-scale overselling. Fix: the FilterString must carry the clause, and Qeasy Cloud should hold an assertion-based unit test for it.
2. Duplicate incremental pulls: When FUpdateTime is a string, >= semantics can be inconsistent across databases. Use uppercase normalization and an exact-timestamp comparison in the mapper.
3. _FNumber vs _FName mismatches: Engineers sometimes map FNumber (code) and FName (name) interchangeably, causing warehouse/material reconciliation to display names instead of codes. Pin the mapping to *_FNumber.
4. String accumulation on quantity fields: Downstream inventory roll-ups concatenate instead of sum because the values are "100.00". The mapper must cast to numeric.
5. Misaligned location-level count: Kingdee supports multi-level locations; some customers use only three levels, yet the integration treats every FStockLocId02~08 as required, breaking non-null validation. Bind enabled levels to the customer's master-data configuration.

When to Choose

Choose executeBillQuery against STK_Inventory when you need to frequently pull online-warehouse sellable / on-book inventory from Kingdee Cloud for distribution to storefront, WMS, or reconciliation systems. For inventory writes or transactional locking, switch to save-class APIs — query-only strategies do not apply.