What Problem This API Solves

In retail and e-commerce scenarios, warehouse master data is the dimensional foundation for inbound/outbound, transfers, and stocktaking documents. Across multiple customer implementations, Kingdee YXC serves as the ERP master data source. The /jdy/v2/bd/store API pulls warehouses incrementally by modification time, then maps them to warehouse codes in business systems such as Jusuitan, ensuring warehouse dimensions remain consistent across cross-system document flows.

API Capability Overview

Authentication: Standard Kingdee YXC WebAPI AccessToken, typically refreshed by a dedicated "Get Latest Authorization" upstream strategy.
Request Method: GET /jdy/v2/bd/store.
Request Parameters: modify_start_time, modify_end_time (incremental timestamps), page (default 1), page_size (default 50).
Response Structure: List-type, each record containing warehouse master fields; primary key id, business code number.
Pagination: Standard pagination via page and page_size; incrementality achieved via time-window cursors.
Strategy Type: QUERY (read-only; Target configured as no-op write).
Schedule: crontab */5 8-20 * * *, polling every 5 minutes during business hours.

Typical Field Mapping

Field Name	Type	Meaning	Practical Notes
id	string	Internal warehouse primary key	Configured as `id` in metadata; usually not used directly across systems
number	string	Warehouse code	Core key for cross-system (e.g., Jusuitan) mapping; must remain unique
name	string	Warehouse name	Used for business display and manual reconciliation
group_id	string	Warehouse category primary key	Optional, for category-level mapping
group_number	string	Warehouse category code	Can be mapped to Jusuitan warehouse types
group_name	string	Warehouse category name	Used for display and operations
is_allow_freight	string	Enable location/freight flag	Semantics differ across versions; verify onsite
is_allow_neg	string	Allow negative stock flag	Determines feasibility of pre-sale/over-sell scenarios
enable	string	Status (1=enabled, 0=disabled)	Disabled warehouses usually excluded from business; handle carefully when filtering

How to Configure on QeasyCloud

On the QeasyCloud Data Integration Platform, this API is typically wrapped as a "Kingdee YXC Adapter". The field mapper automatically recognizes base fields like id, number, name, and enable, eliminating manual JSON parsing. Three configuration points matter:

Select the data query mode and set Target as a "no-op write" to ensure the strategy only pulls master data.
Bind the incremental window to schedule variables so that modify_end_time advances automatically each run, preventing data loss.
Mark number as the business primary key output so downstream product and document sync strategies can reuse the mapping result.

Cross-Implementation Practical Points

Use number, not id, as the business key: Multiple customers hit issues because internal ERP ids are unstable; consistently using codes as the cross-system anchor avoids this.
Overlap in incremental windows: To prevent boundary data loss, rewind the previous window's tail time by 1–2 minutes.
Handling disabled warehouses: Do not filter enable=0 directly, otherwise downstream documents cannot find the warehouse; map status at the target side and retain disabled records.
Warehouse category vs. Jusuitan warehouse types: Jusuitan's main/return/inbound/defective warehouse types must be mapped via a lookup table to Kingdee warehouse categories, not hardcoded in scripts.
Business-hours scheduling: The */5 8-20 * * * schedule has been validated across multiple customers—it balances timeliness and avoids invalid nighttime calls.
Authorization prerequisite: This strategy depends on the "Get Latest Authorization" output; deployment must verify the correct dependency order.

Pitfall Retrospective

Incremental boundary data loss: Using only closed intervals causes duplicate or missing records within the same second. The safe approach is to mix open/closed intervals with a small rewind window.
Excessive page_size triggers throttling: Kingdee YXC truncates responses beyond a threshold. Keep page_size at or below 50 and add retries.
Empty category fields break mapping: Newly created warehouses without a category leave group_* blank, so Jusuitan needs a default fallback warehouse type.
Confused semantics of is_allow_freight: Across YXC versions this may represent freight or location management. Verify with real tenant data before integration; do not blindly copy documentation.
No-op Target misconfigured as a real write: Pollutes downstream systems. Explicitly mark the strategy type as QUERY in metadata to prevent this.

When to Use

This API fits scenarios where Kingdee YXC is the ERP master data source and warehouses need to sync to business systems like Jusuitan, or to provide a warehouse lookup table for downstream product and document synchronization. For bidirectional sync or when Kingdee is not the master source, prefer a generic master data governance solution rather than reusing this query interface.

Kingdee YXC Warehouse Query API (/jdy/v2/bd/store) Field Manual & Practical Tutorial