Kingdee Cloud Warehouse Query API (BD_STOCK) Field Handbook & Practical Tutorial

What Problem This API Solves

In supply chain integration between Wangdiantong and Kingdee Cloud, warehouse master data is the "foundation field" for all inbound/outbound orders, transfer orders, and sales orders. If warehouse codes on both ends don't match, downstream documents either fail to push or push to the wrong physical warehouse. This API uses executeBillQuery to directly read warehouse master data from Kingdee (including custom Wangdiantong mapping fields), establishing cross-system warehouse master mappings and providing a reliable warehouse dictionary for subsequent document synchronization.

API Capability Overview

• Authentication: Standard Kingdee Cloud OAuth/Token authentication, uniformly managed through the Kingdee adapter in Qeasy.
• Request Endpoint: executeBillQuery, Form ID is BD_STOCK (warehouse master data).
• Request Structure: Supports FilterString (Kingdee filter syntax), Limit, StartRow, TopRowCount pagination parameters.
• Response Structure: Standard list-type JSON, fields returned with F prefix; related fields (e.g., use organization) returned in nested form like FUseOrgId.FNumber.
• Pagination Mode: Traditional Limit/StartRow pagination; in real scenarios, warehouse master data typically ranges from hundreds to thousands of records, often pulled in one go, but pagination is still the safe approach.
• Incremental Mode: Based on FModifyDate>='{{LAST_SYNC_TIME|datetime}}' combined with organization filters like FUseOrgId.FNumber='106', with a scheduled task */10 * * * * running every 10 minutes—a stable pattern we've validated across multiple client projects.
• Strategy Nature: Target configured as "empty write operation"—a pure query strategy that doesn't write to the target system, only accumulates master data dictionary.

Typical Field Mapping

How to Configure on Qeasy

On the Qeasy Data Integration Platform, this API is typically invoked using a combination of "Kingdee Cloud Query Adapter" + "Field Mapper":

1. Adapter Selection: Choose "Kingdee Cloud" adapter, select executeBillQuery as the interface action, enter BD_STOCK for FormId.
2. Filter Conditions: FilterString default template FUseOrgId.FNumber='{{ORG_CODE}}' and FModifyDate>='{{LAST_SYNC_TIME|datetime}}', Qeasy's variable placeholders automatically replace the last sync time.
3. Field Mapper: Qeasy's field mapper automatically flattens FUseOrgId.FNumber into fields like FUseOrgId__FNumber, facilitating subsequent master data mapping table writes.
4. Scheduling: Scheduled task */10 * * * * is sufficient; the Qeasy scheduler advances incrementally by time window.
5. Target Side: Since this is a pure query, select "Empty Operation (write empty operation)" for Target, only depositing results into Qeasy's intermediate tables for subsequent document strategies (e.g., sales outbound orders) to reference.

Cross-Solution Practical Points

1. "Related Query" strategy is always a dictionary-type strategy: It doesn't write data itself; its purpose is to provide a "Kingdee warehouse ↔ Wangdiantong warehouse" mapping base table for all downstream warehouse-field-bearing documents.
2. FUseOrgId filter cannot be omitted: Kingdee has a multi-organization architecture; without specifying an organization, you'll pull group-wide warehouses, and irrelevant warehouses will appear in the mapping table—easy to fail when troubleshooting.
3. F_KD_WDTSTOCK is the "yardstick" of Kingdee-Wangdiantong mapping: Across multiple client solutions, whenever this field is empty, it usually means the implementation party hasn't added custom fields for warehouses on the Kingdee side—you need to add field mappings within Kingdee.
4. Verify FModifyDate incremental field validity: We encountered a quirky case at a certain retail enterprise where FModifyDate didn't update (only written once at creation); we eventually fell back to full-comparison.
5. Warehouse code as match key is more stable: FNumber is more suitable as a match key than FName; the probability of name duplication or renaming is much higher than code changes.
6. Empty Target is compliant design: Don't casually add a write target—if a dictionary-type query is mistakenly written back to the target system, it can easily overwrite someone else's warehouse master data.

Pitfall Review

• Pitfall 1: Forgot to include FUseOrgId filter. Pulled group-wide warehouses, test organization warehouses appeared in the mapping table, all downstream document mappings failed. Solution: FilterString must include FUseOrgId.FNumber='{{ORG_CODE}}'; write this into the default template in Qeasy, prohibit running naked.
• Pitfall 2: FStockId used as business code. FStockId is Kingdee's internal primary key (GUID), which changes with data migration or re-import. Solution: Use FNumber as the mapping table primary key; FStockId only for internal deduplication.
• Pitfall 3: F_KD_WDTSTOCK empty, thought there's no data. Warehouses exist on the Kingdee side, but the implementation party didn't add this custom field. Solution: First verify on the Kingdee end whether the field has been added and values maintained, then troubleshoot the API.
• Pitfall 4: Pagination parameter TopRowCount set too large, truncated by Kingdee. Kingdee limits single-return rows (commonly 5000); exceeding this gets truncated without error. Solution: The safe approach is Limit=2000, explicit pagination, and verify total counts.
• Pitfall 5: Incremental timestamp timezone drift. When the Kingdee server timezone differs from the Qeasy scheduler timezone, you'll encounter "just-modified warehouses not pulled" or "old data repeatedly pulled". Solution: Explicitly lock the timezone (typically UTC+8) in Qeasy's scheduling configuration; ensure the time variable in FilterString also has a timezone suffix.

When to Use This

When you need to integrate Wangdiantong Kingdee Cloud supply chain, and business documents (e.g., sales outbound, transfer orders) depend on warehouse code mapping between both ends, you should run this "related query" strategy. It solves only one thing: accumulating a clean, incremental, organization-dimensioned warehouse master data dictionary for all downstream strategies to reuse. For document-level sync, inbound/outbound validation, etc., we recommend building this base table first before discussing downstream work.