Authoritative Tutorial on Kingdee Cloud Xingchen [Linked Query] Warehouse API Field Handbook

What Problem This API Solves

In the supply chain integration between the WDT (Wangdiantong) platform and Kingdee Cloud Xingchen, the "warehouse" is the root master data for inbound orders, outbound orders, transfer orders, and inventory queries. We use Kingdee Cloud Xingchen V2's /jdy/v2/bd/store API for a pure query linkage to pull warehouse codes, names, categories, location management flags, and negative-stock configurations, then map them against WDT warehouses / store warehouses and provide a unified reference for downstream document warehouse mappings. The Target side is configured as a "Write No-Op", positioning this strategy as a "master data pre-query" callable by other write strategies.

API Capability Overview

• Endpoint: /jdy/v2/bd/store (Kingdee Cloud Xingchen V2 WebAPI)
• Method: GET
• Strategy Type: QUERY, read-only, no write to the target system
• Authentication: Standard Kingdee Cloud Xingchen OAuth / AccessToken; on the Qeasy platform this is handled by the Kingdee Cloud Xingchen V2 adapter, which manages credential refresh automatically
• Filter Parameters: enable (default 1, only enabled warehouses), group_id (filter by warehouse category)
• Pagination: page (default 1), page_size (controlled by the Qeasy variable PAGINATION_PAGE_SIZE, typically 100~500)
• Response Structure: Array-style paginated response; each record contains the primary key id, business code number, name, category, location management flag, and negative-stock flag
• Scheduling: In multiple customer projects, the cron is consistently set to 15 3 * * * daily, avoiding peak outbound business hours

Typical Field Mapping

How to Configure on Qeasy

The Qeasy Data Integration Platform wraps this API in a very streamlined way:

1. Adapter: In the "Data Source" step, select "Kingdee Cloud Xingchen V2" and enter the authorization info (credentials are managed centrally by the platform — no need to hardcode access_token in the strategy).
2. Data Object: Pick bd/store (warehouse master data); Qeasy will automatically load id, number, enable, group_id, etc. into the field mapper.
3. Filtering and Pagination: Tick enable=1 in the strategy config; if a specific category is required, add group_id in the "Request Parameters"; bind the page size to the environment variable PAGINATION_PAGE_SIZE.
4. Target Side: Set the Target to "Write No-Op" to clearly mark this as a pure query linkage node that other write strategies will depend on.
5. Scheduling: Set the cron to 15 3 * * *, aligned with Kingdee-side inventory initialization timing.
6. Dependency Orchestration: Qeasy's strategy dependency graph automatically identifies this query as a prerequisite node, so downstream write strategies such as "Sales Outbound Sync" or "Transfer Order Sync" can directly reference warehouse_code (number) inside the field mapper.

Cross-Scenario Best Practices

From multiple customer projects we have distilled the following common lessons:

• Prefer number as the business mapping key: id can change across system upgrades or tenant migrations, while business codes remain stable, giving better long-term integration stability.
• Always pre-filter on enable status: Once a disabled warehouse participates in downstream document mapping, outbound documents will fail or inventory will get corrupted; defaulting to enable=1 is the safe approach.
• Category codes beat category names: Renaming a category with the same name happens often; group_number is the truly stable anchor for mapping.
• Pass through location and negative-stock flags: Both flags directly affect downstream business rules and should not be discarded just because the current scenario does not use them.
• Clearly label pure-query nodes: Set the Target to "Write No-Op" and tag the strategy type as QUERY so that the dependency graph remains readable.
• Schedule away from business peaks: 03:15 AM is an empirical sweet spot — it avoids the daytime high-frequency write window and finishes the master data refresh before the early shift starts.

Pitfall Review

• Pitfall 1: Using id as the WDT-side mapping key. After a system upgrade, Kingdee's id changed and all historical documents became orphaned. Fix: switch to number as the mapping key; Qeasy's field mapper can swap it in one click.
• Pitfall 2: Forgetting to filter disabled warehouses. After pulling warehouses with enable=0, downstream outbound documents referencing them were rejected by Kingdee. Fix: hard-code the enable=1 filter in the request parameters.
• Pitfall 3: Using group_name as the category mapping key. A customer renamed the "Finished Goods Warehouse" category, breaking all downstream strategies depending on that mapping. Fix: standardize on group_number instead.
• Pitfall 4: Hard-coding an excessively large page_size. A single request for 5000 records triggered Kingdee's rate limit. Fix: hand the page_size over to the PAGINATION_PAGE_SIZE variable; setting it to 200 in Qeasy solves it.
• Pitfall 5: Forgetting to pass through is_allow_neg. A retail customer's virtual warehouse allowed negative stock, but default business rules blocked its outbound flow. Fix: explicitly pass this field through in the field mapper.

When to Use

The "Kingdee Cloud Xingchen Warehouse Query" is suitable for WDT ↔ Kingdee Cloud Xingchen supply chain integration scenarios that require warehouse master data linkage and cross-system warehouse code mapping, or that need to provide a warehouse reference baseline for downstream write strategies. Being a pure query, it must be paired with other write strategies to form a complete business loop. If the customer does not use Kingdee for accounting or has no cross-system warehouse mapping needs, this node can be skipped.