Jushuitan Warehouse Query API Tutorial: A Field Mapping & Cross-System Integration Handbook

What This API Solves

Warehouse master data is the most overlooked yet error-prone part of any ERP integration between e-commerce WMS and finance/supply-chain ERP. Jushuitan's /open/wms/partner/query API queries sub-warehouse master data, allowing us to pull sub-warehouse IDs, names, and parent-warehouse ownership into the downstream system. It serves as the mapping foundation for systems like Kingdee Cloud, preventing failures in subsequent outbound, inbound, and transfer documents caused by inconsistent warehouse codes.

API Capabilities Overview

• Authentication: Standard OAuth/AppToken authentication for the Jushuitan Open Platform; the access_token must be carried in the request header.
• Request Structure: Both POST and GET are supported (depending on the adapter version). The core pagination parameters are page_index (default 1) and page_size (default 30).
• Response Structure: Returns an array of sub-warehouses, each element containing fields such as wms_co_id, name, co_id, and is_main.
• Pagination/Incremental Mode: Pure paginated pull with no built-in incremental cursor. In practice, we usually schedule timed full-pagination scans and rely on wms_co_id for idempotent deduplication downstream.
• Execution Frequency: A common cron configuration is 10-59/59 7-23 * * *, triggering every 59 minutes between 7 and 23 o'clock to avoid the early-morning maintenance window.

Typical Field Mapping

How to Configure on QeasyCloud

In QeasyCloud Data Integration Platform, this API has been packaged as a standard WMS adapter. We typically follow these steps:

1. Create a Jushuitan connection under "Data Source," fill in the AppKey/Secret, and let the platform handle token refresh.
2. Select the /open/wms/partner/query adapter template; it auto-imports the page_index and page_size pagination variables.
3. In the metadata, set id to wms_co_id and number to name; enable idCheck based on the scenario.
4. Choose "Empty Write" on the Target side, declaring this as a pure query strategy that only outputs intermediate results.
5. QeasyCloud's field mapper automatically normalizes the string boolean value of is_main, preventing type validation failures on the downstream Kingdee side.

Cross-Scenario Practical Points

• Warehouse master data first: All outbound, inbound, and transfer strategies depend on the warehouse mapping table; complete warehouse queries before enabling business document strategies.
• Don't drop the parent-sub hierarchy: co_id must be synchronized downstream, or Kingdee will misidentify the sub-warehouse as a top-level warehouse, causing inventory organization chaos.
• Combine keys for same-named sub-warehouses: Matching only by name will collide in multi-company scenarios; use the composite key wms_co_id + co_id.
• Pagination pace and rate limiting: Jushuitan enforces QPS limits per tenant; keep page_size below 50 and reserve a token-refresh window in the schedule.
• Reuse value of pure query strategies: Persist warehouse query results in an intermediate table so multiple downstream strategies share the same master data, reducing maintenance cost.
• Idempotent writes are the baseline: Even if the Target is an empty operation, downstream consumers must be idempotent by wms_co_id, otherwise duplicate pushes will pollute the mapping table.

Pitfall Retrospective

1. is_main treated as a boolean field: Kingdee expects a boolean type, but Jushuitan returns the string "true"; a direct mapping will fail validation. The safe approach is an explicit boolean conversion in the mapper.
2. Forgetting co_id causes downstream hierarchy chaos: A retail enterprise's first integration only synchronized wms_co_id and name, resulting in Kingdee attaching sub-warehouses to the wrong parent warehouse; subsequent inventory transfers all failed to reconcile.
3. Downstream triggered before pagination finishes: The scheduled task triggered Kingdee writes right after the first page, causing half the sub-warehouses to be missing. The recommended approach in QeasyCloud is to drive downstream strategies with a "full-load complete" event.
4. Cron triggers collide with token expiry: The default token lifetime is 2 hours, so overnight tasks easily hit the expiry window. A safe approach is to set the cron start point 10 minutes after the hour and enable auto-renewal on the platform.
5. Historical documents lost after warehouse rename: Jushuitan allows renaming sub-warehouses; if the downstream only matches by name, old documents will fail to locate the warehouse. Always use wms_co_id as the unique association key.

When to Use

This API is suitable for warehouse master data synchronization between e-commerce WMS and finance/supply-chain ERP, cross-system warehouse mapping, and warehouse field conversion for inbound, outbound, and transfer documents. It is not suitable for real-time inventory level queries—inventory data should go through a dedicated inventory query API, not this sub-warehouse master data API.