Kingdee Cloud Galaxy Warehouse Query API Field Handbook: An Authoritative Tutorial from Query to Code Mapping

What This Interface Solves

In cross-border supply chain integration, warehouse codes are the "translator" that binds materials, customers, suppliers, and documents together. Kingdee Cloud Galaxy's warehouse query interface (using executeBillQuery on BD_Stock) is the mandatory precursor to opening up master data and all business documents. Without accurate warehouse mapping, downstream sales outbound, purchase inbound, assembly/disassembly, and transfer documents will fail due to mismatched organizations/warehouses. We have repeatedly verified in multiple customer projects: stabilize this mapping table first, and the subsequent 26 strategies can proceed smoothly.

Interface Capability Overview

• Authentication: Kingdee Cloud Galaxy Open Platform uses an OAuth signature mechanism combining appId + appSecret + acctId + tenantId. Qeasy's "Kingdee Cloud Galaxy Adapter" has encapsulated this signature into visual credentials.
• Request Structure: POST form submission to /k3cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.executeBillQuery, with core parameters formId=BD_Stock, fieldKeys, filterString, limit, startRow, orderString.
• Response Structure: A JSON-wrapped 2D array Result.Result, where each row corresponds to a warehouse. Pagination is controlled by limit + startRow, with Kingdee's default page cap at 5000 rows.
• Incremental Mode: Use FModifyDate >= ${lastRunTime} as the incremental cursor; during full initialization, pull once with an empty filter.

Typical Field Mapping

How to Configure on Qeasy

In Qeasy, this interface is typically called using a combination of "Kingdee Cloud Galaxy Query Adapter + Field Mapper":

1. Data Source Node: Select "Kingdee Cloud Galaxy Query", fill in appId, appSecret, acctId, tenantId, and choose BD_Stock as formId;
2. Field Pulling: In the "Field Mapper", check FStockId, FNumber, FName, FStockOrgId.FNumber, FCreateOrgId.FNumber;
3. Incremental Cursor: Qeasy's field mapper automatically recognizes FModifyDate and generates a filterString like FModifyDate >= '2026-03-01 00:00:00';
4. Mapping Storage: Query results are directly written to the "Mabang Warehouse Mapping Table" intermediate storage for subsequent strategies 7 and 8 (Mabang warehouse ↔ Kingdee warehouse);
5. Scheduling Strategy: Recommend hourly increments; full initialization should be scheduled during off-peak hours.

Cross-Scenario Practical Points

1. Master Data First: In all the scenarios we've encountered, warehouse queries must complete their first run before suppliers and materials, otherwise business documents will fail in bulk due to missing warehouse codes.
2. Bidirectional Mapping Tables: Kingdee FNumber ↔ Mabang warehouse_id/wid must be stored bidirectionally; one-way mapping breaks in cross-org scenarios.
3. Organization + Warehouse Dual-Key Binding: Cross-border retail enterprises often have multiple inventory organizations; FNumber must be unique under its FStockOrgId. Qeasy's field mapper supports secondary mapping based on organization context.
4. Stable Incremental Cursor: Kingdee's FModifyDate is precise to the second, and Qeasy stores it in UTC by default. In cross-timezone scenarios, explicitly specify the +8 timezone to avoid missing records.
5. Filter Disabled Warehouses: Append FForbidStatus = 'A' in filterString to reduce invalid data sync and facilitate reconciliation.
6. Cache Query Results: Qeasy's intermediate storage diffs current results against previous results, pushing only changed rows, saving API quota.

Pitfall Review

• Pitfall 1: FNumber Duplicate Across Organizations. A retail enterprise shared the same code across multiple organizations, causing downstream to write to the wrong inventory. This is easy to flip; the safe approach is to force FStockOrgId.FNumber = '${orgCode}' in the filterString.
• Pitfall 2: Incorrect Field Path Writing. FStockOrgId.FNumber must have a capital F and be declared as a whole in fieldKeys, not split into FStockOrgId and FNumber columns.
• Pitfall 3: Last Page Missing in Pagination. When the total number of warehouses is exactly a multiple of 5000, the last page returns an empty array. Need to enable "Empty Page Termination" in Qeasy and verify the total count.
• Pitfall 4: Timezone Drift. The incremental cursor is stored in UTC, but Kingdee's returned FModifyDate is a +8 timezone string; without conversion, data from the last 8 hours will be missed.
• Pitfall 5: Credential Expiry Without Retry. If OAuth token failure is not auto-refreshed, the entire mapping table will stall. Qeasy's adapter enables token refresh and 3 retries by default.

When to Use

This interface is suitable for all bidirectional integration scenarios where Kingdee Cloud Galaxy warehouse master data needs to be synced to third-party ERPs (WMS, cross-border ERP, e-commerce middle platforms); it is not suitable for lightweight integrations with a single organization, manually maintained warehouses, and no need for code mapping. In our view, as long as the downstream system has the concept of "warehouse code" and it differs from Kingdee, this interface is mandatory.