Kingdee Warehouse Query API Field Handbook: A Cross-Scenario Engineering Tutorial

What This Interface Solves

In our multi-system integration projects, warehouse master data is the foundation for sales orders, purchase receipts, transfers, and inventory counts. When integrating Xiaoman OKKICRM, Jushuitan, or Wangdiantong with Kingdee, the first step is almost always pulling Kingdee's warehouse archive into a mapping table so downstream documents know "which Kingdee record corresponds to this warehouse code." Kingdee has two branches: Kingdee YXC V2 uses a lightweight WebAPI (/jdy/v2/bd/store), while Kingdee Cloud uses the enterprise-grade executeBillQuery (FormId: BD_STOCK). This tutorial explains the fields, incremental patterns, and pitfalls of both interfaces in one place.

Interface Capability Overview

Kingdee YXC V2: RESTful GET request to /jdy/v2/bd/store. Supports incremental filtering by modify_start_time and modify_end_time in millisecond timestamps. Pagination uses page (default 1) and page_size (default 100). Optional request filter enable (default 1, only enabled warehouses). Strategy type is QUERY_ONLY with a "null write" target.

Kingdee Cloud: Submits form BD_STOCK through the generic document query interface executeBillQuery, using Kingdee's FilterString syntax (e.g., FNumber = 'CK001', FAuditDate>='{{LAST_SYNC_TIME}}'). Pagination uses Limit (default 2000), StartRow, and TopRowCount. Also a QUERY_ONLY strategy with null-write target.

In Qeasy, both interfaces are registered as "query-type adapters" with Kingdee as the source and a null-write marker on the target, scheduled via crontab in the strategy orchestration.

Typical Field Mapping

How to Configure on Qeasy

In Qeasy Data Integration Platform, "Query Kingdee Warehouse" is typically packaged as a QUERY_ONLY source adapter. Key configuration steps we follow:

1. Adapter selection: Choose "Kingdee YXC V2" or "Kingdee Cloud" as the source; the platform auto-loads the corresponding endpoint template and field metadata.
2. Field mapper: Qeasy's field mapper automatically recognizes id, number, name as primary key, code, and name, generating warehouse_id, warehouse_code, warehouse_name in the target schema for downstream reuse.
3. Incremental parameters: For YXC V2, configure modify_start_time/modify_end_time directly; for Cloud, embed FAuditDate>='{{LAST_SYNC_TIME|dateTime}}' in FilterString—Qeasy's expression engine renders the last sync time automatically.
4. Null target operation: Since this is a pure query, select "Null Operation" on the target side. Data lands in Qeasy's mid-tier data pool, available for other strategies (like sales order warehouse mapping) to look up by code.

Cross-Scenario Engineering Takeaways

From multiple customer projects, we distill these common lessons:

1. Code field is the lifeline of cross-system mapping: Whether YXC or Cloud, number/FNumber is the business-side unique identifier—always use it as the mapping table's primary key, not id/FStockId.
2. Prefer modification time over creation time for incremental sync: Warehouses get renamed, regrouped, and toggled after creation—modify_start_time (YXC) or FAuditDate (Cloud) is more reliable.
3. Apply enable-status filtering on the request side: Only sync enable=1 warehouses by default; disabled ones don't participate in business flow.
4. Match page size to the interface's tolerance: YXC V2 defaults to 100 rows/page (conservative); Cloud's Limit=2000 is the single-call ceiling—use 1000-2000 to balance performance and stability.
5. Semantic gap in group fields: YXC V2 splits into group_id/number/name; Cloud returns only FGroup. In Qeasy's mapper, you must merge or split fields accordingly.
6. QUERY_ONLY strategies must pair with null target operation: Otherwise the scheduler errors out—this is the most common configuration pitfall for newcomers.

Pitfall Postmortem

1. Pitfall 1: Using name for cross-system matching. In one retail project, renaming a warehouse broke all downstream sales order mappings. The safe approach: always match by code field, use name only for manual verification.

2. Pitfall 2: No upper bound on incremental time window. If modify_end_time is omitted on YXC V2, the call pulls all increments up to the current moment and eventually exhausts memory on long-running schedules. The safe approach: each run only fetches the [last_sync → now] window with a strict end_time cap.

3. Pitfall 3: Wrong delimiter in Cloud FilterString. Kingdee's filter syntax requires single quotes around strings; double quotes return 400. FNumber = "CK001" is wrong—correct: FNumber = 'CK001'.

4. Pitfall 4: Position management field misalignment. YXC V2's is_allow_freight is a warehouse-level switch, but position details require a separate /jdy/v2/bd/position endpoint—don't expect position rows in this query.

5. Pitfall 5: Negative stock config not linked to business rules. is_allow_neg=1 is just a technical switch; whether ship-before-receive is allowed depends on the customer's business policy. In Qeasy, map it to a "business rule tag" field that downstream inventory validation strategies can reference.

When to Use

This interface applies to all scenarios that need to sync Kingdee warehouse archives into a mid-tier platform and build cross-system warehouse mapping tables, covering integrations with Xiaoman CRM, Jushuitan, Wangdiantong, and other heterogeneous systems. Boundary note: If a customer uses both YXC V2 and Cloud (hybrid deployment), you must configure two separate source adapters in Qeasy and merge via the unified warehouse_code primary key; if you only need the warehouse name for display, a single-record query is enough—no need to pull the full archive.