Kingdee Cloud Xingchen Material Query API: The Definitive Field Handbook & Qeasy Configuration Guide
What This API Solves
In supply chain integration projects between Jushuitan and Kingdee Cloud Xingchen, the Material Query API (/jdy/v2/bd/material) acts as the master data hub. It pulls material records from Xingchen, maps them against Jushuitan product codes, and powers item mapping and reconciliation for sales outbound, purchase inbound, and inventory documents. It is the dictionary source for the entire integration chain.
API Capability Overview
- Authentication: Kingdee Open Platform OAuth 2.0. Exchange AppKey/AppSecret for an access_token and pass it via the request header.
- Request Structure: GET
/jdy/v2/bd/materialwith parametersmodify_start_time,modify_end_time(millisecond timestamps),page, andpage_size. - Response Structure: An outer
dataarray containing material records with fields such as id, number, and name; pagination info is exposed viatotal_count. - Pagination / Incremental Mode: Modification-time window-based incremental pull plus standard pagination, typically combined with
LAST_SYNC_TIMEandCURRENT_TIMEvariables. - Detail Endpoint:
/jdy/v2/bd/material_detailis used to enrich multi-unit and auxiliary attribute information.
Typical Field Mapping
| Field | Type | Meaning | Practical Notes |
|---|---|---|---|
| id | string | Internal Xingchen primary key | Used only inside Xingchen; use number for cross-system reconciliation |
| number | string | Material code | Core field for mapping with Jushuitan; keep globally unique |
| name | string | Material name | Basis for display and reconciliation; watch for duplicates |
| parent_id/number/name | string | Parent category | Recursively traverse when handling tree structures |
| base_unit_id/number/name | string | Base unit of measure | Foundation of UoM conversion; build a mapping table with Jushuitan |
| units | object | Multi-unit config | Includes auxiliary units and conversion ratios; must be parsed when multi-unit is enabled |
| is_multi_unit | string | Whether multi-unit is enabled | Decides whether to expand the units object |
| barcode | string | Primary barcode | Reconcile with Jushuitan barcode field |
| check_type | string | Product type: 1 normal / 2 kit / 3 service | Kit products need child-item expansion |
| brand_id/number/name | string | Brand dimension | Used for brand-level filtering and reporting |
| model | string | Specification | Map against Jushuitan spec field |
| help_code | string | Memo code | Auxiliary field for quick search |
| is_serial / is_batch / is_kf_period / kf_period_type | string | Serial / batch / shelf life | Drives inventory business logic branches |
| is_asst_attr / is_show_aux_barcode | string | Auxiliary attributes | Affects SKU-level expansion |
| mul_label | object | Material tag set | Supports multi-dimensional categorization |
Configuring on Qeasy
In the Qeasy Data Integration Platform, this API is pre-packaged as the "Kingdee Cloud Xingchen - Material Query" adapter. Engineers only need to configure tenant authorization to enable it.
- Data Source Configuration: Select the "Kingdee Cloud Xingchen V2" adapter, fill in AppKey/AppSecret and book info; Qeasy automatically maintains token refresh.
- Request Parameter Orchestration: Qeasy supports configuring
LAST_SYNC_TIMEandCURRENT_TIMEas built-in time variables, triggering incremental pulls on a*/10 7-22 * * *schedule. - Field Mapper: Qeasy's field mapper automatically recognizes
idandnumberas primary key and code fields, and pre-generates a generic mapping template to the Jushuitan product object (material_id, material_code, material_name, etc.). - Empty-operation Target: Since this strategy is query-only, the Target is configured as a no-op write, only landing material data into the Qeasy staging area for downstream document sync strategies to consume.
- Detail Enrichment Hook: A "detail trigger" can be configured in Qeasy to automatically call
material_detailfor multi-unit and auxiliary attributes.
Cross-Scenario Best Practices
We have distilled the following common lessons from multiple customer projects:
- Code over ID: Always use
numberas the cross-system reconciliation key.idshould only be used for internal Xingchen traceability to avoid failures from ID changes. - *Timestamps Must Be 1000: The API requires millisecond timestamps. Passing seconds returns an empty set, the most common pitfall.
- Set page_size Between 20 and 50: Too large triggers rate limits; too small multiplies request counts.
- Multi-unit Objects Must Be Flattened: Raw
unitsobjects cannot perform conversion downstream; use a script node in Qeasy to flatten them. - Handle check_type=2 Kits Specifically: Kits require recursive child-item expansion; otherwise outbound quantities will be incorrect.
- Add Overlap to Incremental Windows: Keep a 5–10 minute overlap window to prevent edge data loss between scheduled runs.
Pitfall Retrospective
- Wrong timestamp unit: Passing second-level timestamps causes the API to return empty data. The safe approach is to multiply by 1000 in a Qeasy variable before sending.
- page_size too large triggers rate limits: A project setting 200 frequently received HTTP 429. Reducing to 50 stabilized the run.
- Unflattened multi-unit fields distort inventory: Raw
unitslanded in downstream documents without conversion logic. Always flatten in a Qeasy script node. - Edge data loss in incremental pulls: 10-minute intervals without overlap risk boundary data loss. Add a 5-minute overlap and rely on
modify_end_timeas a safety net. - Kits not recursively expanded: Only the parent of check_type=2 kits was pulled, causing quantity mismatches on sales outbound. Add child expansion logic in Qeasy.
When to Use It
This API is ideal when Xingchen is the product master data source and integrates with front-end systems such as Jushuitan, especially for high-frequency incremental material sync that powers sales, purchase, and inventory document mapping. If Xingchen is not the master, or only a one-time full import is needed, this incremental strategy is unnecessary.