Kingdee Cloud Xingchen Warehouse Query API Tutorial: From Field Mapping to Incremental Sync

What This API Solves

Warehouses are the cornerstone of master data in supply chain integration. Across multiple real customer projects, we often need to sync warehouses from Kingdee Cloud Xingchen to Guanyi Cloud (or vice versa) for inventory dimension matching, inbound/outbound document selection, and multi-warehouse transfers. The /jdy/v2/bd/store API is designed exactly for this as a read-only query endpoint, supporting incremental pulls by modification time to avoid the performance and consistency issues of full-table refreshes.

API Capability Overview

• Authentication: Kingdee Cloud Xingchen WebAPI standard Access Token authentication, managed and auto-refreshed by the Qeasy adapter.
• Request Method: GET, path /jdy/v2/bd/store.
• Request Parameters: modify_start_time / modify_end_time (millisecond timestamps for incremental), page (default 1), page_size (controlled by the PAGINATION_PAGE_SIZE variable), enable (default 1 to query only enabled warehouses), group_id (filter by warehouse category).
• Response Structure: JSON array; each record contains id, number, name, enable, groupid_id, groupid_number, groupid_name, isallowfreight, isallowneg, etc.
• Pagination Mode: Traditional page-based pagination, combined with incremental time windows enables resumable pulls in Qeasy.
• Incremental Mode: Filtering by modification time via modify_start_time and modify_end_time is the officially recommended sync strategy.

Typical Field Mapping

How to Configure on Qeasy

In the Qeasy Data Integration platform, calls to this API typically use a Kingdee Cloud Xingchen V2 Adapter + pure query strategy combination:

1. Adapter Selection: Choose "Kingdee Cloud Xingchen V2" in the source system connector, fill in tenant ID and app credentials (uniformly encrypted and stored by Qeasy's credential manager).
2. Strategy Type: Select QUERY (pure query). Configure Target as "Write Null Operation" so data is not written to the target system; it is only produced for downstream strategies to consume.
3. Field Mapper Configuration: Qeasy's field mapper automatically flattens nested fields such as groupid_id and isallowfreight, allowing you to drag-and-drop directly to target fields.
4. Incremental Variables: Define PAGINATION_PAGE_SIZE (e.g., 100) in Qeasy's "Schedule Variables" and bind the previous sync's modify_end_time in the incremental window configuration.
5. Scheduled Execution: It is recommended to follow the */10 7-21 * * * high-frequency window to cover store operating hours.

Cross-Solution Practical Points

1. number is the lifeline of cross-system mapping. Across multiple customer projects, inconsistent warehouse codes are the #1 cause of transfer failures. Be sure to build a "code mapping table" in Qeasy and validate uniqueness.
2. Define a clear handling strategy for disabled warehouses. Disabled does not mean deleted; if the target system does not filter, documents cannot pick a warehouse.
3. Leave a 1–2 minute overlap in incremental windows. Kingdee's modification timestamp precision may differ from local clocks; an overlap window prevents missed boundary data.
4. Do not be greedy with page_size. In real scenarios, exceeding 200 easily triggers rate limiting; Qeasy's default of 100 is a safe choice.
5. Sync warehouse categories (groupid) separately. Maintaining them as an independent dimension table makes downstream filtering by category much more efficient.
6. id and number must be declared separately in Qeasy metadata. This is a hard requirement for Kingdee's query API; missing either results in an empty page response.

Pitfall Recap

• Pitfall 1: Misinterpreting isallowfreight. We once synced it as "allow freight" to the target system at a retail enterprise, which incorrectly enabled location management downstream. This is a common trap—the safe approach is to add a note in the Qeasy field mapper clarifying that it is the location management switch.
• Pitfall 2: Timestamp unit mismatch. Kingdee uses millisecond timestamps, while some upstream systems provide ISO strings. Passing them directly invalidates the incremental window. Use the toUnixMillis() function in Qeasy for unified conversion.
• Pitfall 3: Pagination infinite loop. When page_size exactly equals the total count and page is not incremented, the pull loops indefinitely. Qeasy's paginator detects and stops this by default, but it is still recommended to enable logs during debugging.
• Pitfall 4: enable=1 default filters out disabled warehouses. If the business needs full data (including historically disabled warehouses), you must explicitly pass enable as empty or 0, otherwise disabled warehouses will never reach downstream.
• Pitfall 5: No data outside the scheduled window. */10 7-21 * * * means no pulls between 22:00 and 06:59. If overnight transfers are needed, adjust the cron or enable a "catch-up pull" strategy in Qeasy.

When to Use

When your integration scenario requires incremental sync of Kingdee Cloud Xingchen warehouse master data to downstream systems (such as Guanyi Cloud, ERP, BI) by modification time, and only reads are needed without write-back, this API is the optimal choice. If reverse writes or complex transactions are required, switch to Kingdee's save-type API combination instead.