Kingdee Cloud Xingchen Material Query API Tutorial: Field Mapping to Qeasy Integration

What Problem Does This API Solve

In retail and e-commerce integration scenarios, material master data is the foundation of purchasing, sales, inventory, and inbound/outbound workflows. /jdy/v2/bd/material is a paginated query API provided by Kingdee Cloud Xingchen V2, supporting incremental pulls by modification time. Across multiple real customer projects, we use it to sync Kingdee materials into the Qeasy Data Integration platform, mapping them against WDT (WangDianTong) products, sales order fields, inventory validation, and product master data sync. A clean material master flow is the prerequisite for all downstream document processing.

API Capability Overview

• Authentication: Kingdee Cloud Xingchen V2 WebAPI standard auth; credentials managed centrally by the Qeasy connector.
• Request Method: GET /jdy/v2/bd/material
• Strategy Type: QUERY_ONLY (Target side is configured as a no-op write, no data written back to the target system)
• Pagination Parameters: page (default 1), page_size (default 100 records).
• Incremental Parameters: modify_start_time / modify_end_time, millisecond timestamps mapped to Qeasy variables LAST_SYNC_TIME and CURRENT_TIME.
• Scheduling: Typically configured to run daily at 02:03 (crontab 3 2 * * *), avoiding business peak hours.
• Response Structure: Paginated material list with primary key id, business code number, plus hierarchy, brand, unit of measure, batch/shelf-life attributes.

Typical Field Mappings

How to Configure on Qeasy

On the Qeasy Data Integration platform, the Kingdee Cloud Xingchen material query API is typically encapsulated as follows:

1. Adapter Selection: Choose "Kingdee Cloud Xingchen V2" as the source; Qeasy has built-in request templates for /jdy/v2/bd/material, simply fill in the connector credentials.
2. Strategy Type: Select QUERY_ONLY, configure the Target side as a "no-op write"; the platform only persists data to the staging area for other strategies to consume.
3. Incremental Configuration: Qeasy scheduling variables LAST_SYNC_TIME and CURRENT_TIME are automatically injected into modify_start_time / modify_end_time, no manual millisecond conversion needed.
4. Pagination Control: page_size defaults to 100; Qeasy's field mapper automatically paginates and merges results, no loop scripting required.
5. Field Mapper: id/number map directly to material_id/material_code; object-type units and mul_label can be expanded via Qeasy's JSON expander to map child fields to corresponding WDT fields.
6. Dependency Orchestration: This strategy is often used as a prerequisite for "Query WDT Products"; sequence is controlled via depends_on.

Cross-Project Best Practices

1. number is the lifeline of cross-system mapping: In all customer projects, number is the primary association key between Kingdee material and WDT product/spec; Qeasy's field mapper marks it as the business code field by default.
2. Don't cross days with incremental windows: Validated across multiple projects, setting modify_end_time to CURRENT_TIME - buffer (e.g., 5 minutes) is more stable than using CURRENT_TIME directly, avoiding boundary data loss.
3. page_size 100 is the sweet spot: Tested in practice, 100 records per page is most stable within Kingdee's rate limits; exceeding 200 easily triggers throttling.
4. Flatten object fields in advance: object-type units and mul_label must be flattened in Qeasy, otherwise downstream strategies cannot access conversion rates and tag values.
5. Bundle materials with check_type=2 require decomposition: Multiple retail customers have encountered inventory confusion when bundle materials are directly mapped; adding a converter in Qeasy to split into child items is the fix.
6. Schedule tasks at dawn: Customer testing shows 02:03 batch runs hit the lowest Kingdee-side load, avoiding peak hours and reducing throttling probability.

Pitfall Retrospective

1. Milliseconds vs seconds timestamp confusion: Kingdee uses milliseconds, but some legacy scripts pass second-level timestamps, causing incremental window misalignment — this is where it goes wrong; the safe approach is to force multiply by 1000 in Qeasy's variable mapping.
2. parent_id is empty string, not null: Kingdee root-level materials have parent_id as empty string, not null; when mapped to WDT categories it becomes empty value — remember to normalize empty strings in Qeasy.
3. units conversion rate direction is not fixed: The direction in units is not always consistent; customers have encountered reversed rates in practice — the safe approach is to run a sampling check after sync.
4. barcode only returns primary code: Kingdee returns only the primary barcode; multi-barcodes are in auxiliary attributes — enable is_show_aux_barcode and pull auxiliary attributes in full.
5. Batch/shelf-life fields are switches, not values: is_batch and is_kf_period are only enable flags; actual batch numbers and expiry dates are in the inventory API — don't try to parse them during material sync.

When to Use

Applicable for WDT/e-commerce frontend ↔ Kingdee Cloud Xingchen ERP material master sync, code mapping, and basic data distribution scenarios. Use this API when you need incremental pulls by modification time, code mapping, or laying the foundation for downstream order and inventory processes. For real-time inventory or batch details, use the inventory query API instead of the material API.