What Problem This Interface Solves

In retail and e-commerce supply chain integration scenarios, product master data is the hub connecting ERP with front-end business systems. We often need to map material (product) master data in Kingdee Cloud Xingchen with products/SKUs in systems like WDT and e-commerce platforms, providing foundational data validation for subsequent sales orders, purchase orders, and inventory synchronization. The /jdy/v2/bd/material query interface is built exactly for this purpose, supporting incremental pulls by modification time and paginated traversal, making it the core entry point for product master data linkage.

Interface Capability Overview

Source System: Kingdee Cloud Xingchen V2 WebAPI, Basic Data - Material
Endpoints: /jdy/v2/bd/material (list query), /jdy/v2/bd/material_detail (detail query by id)
HTTP Method: GET
Strategy Type: QUERY (read-only, Target end uses empty write operation, no data landing)
Authentication: Kingdee Cloud Xingchen OpenAPI standard access_token authentication (obtained via /jdy/v2/auth/login)
Incremental Parameters: modify_start_time, modify_end_time, both in millisecond timestamps
Pagination Parameters: page (default 1), page_size (default 20, recommended not exceeding 100 in practice)
Primary Key Field: id
Code Field: number
Scheduled Task: Typically configured to run daily at 3:15 AM for off-peak batch processing

Typical Field Mapping

Field Name	Type	Meaning	Practical Notes
id	string	Material primary key ID	Unique anchor for cross-system mapping, must be saved as the primary key in the mapping table
number	string	Material business code	Maps to WDT SKU code and sales order product code, commonly used by front-end
name	string	Material name	For display, watch out for special characters and whitespace cleaning
parent_id / parent_number / parent_name	string	Parent material/category	Builds product tree hierarchy, used for category mapping
model	string	Specification model	Maps one-to-one with WDT specification field
barcode	string	Primary barcode	Key field for scanning scenarios, null values need fallback handling
url	string	Product main image URL	Beware of hotlink protection, some CDN domains need whitelisting
help_code	string	Mnemonic code	Accelerates search, ignorable but worth keeping
remark	string	Description/remarks	Long text field, watch out for length truncation
check_type	string	Product category: 1 Normal 2 Bundle 3 Service	Differentiates business types, special handling needed for bundle products when splitting orders
brand_id / brand_number / brand_name	string	Brand triplet	Foundation for brand-dimension statistics and filtering
producing_pace	string	Origin	Mandatory for some industry compliance
base_unit_id / base_unit_number / base_unit_name	string	Base unit of measure	Maps to WDT unit of measure, units need to be expanded in multi-unit scenarios
is_multi_unit	string	Whether multi-unit is enabled	Only true when units field has values, need null defense
is_serial / is_batch / is_kf_period / is_weight	string	Serial/batch/shelf-life/weighing flags	Determines downstream inventory and order business logic branches
is_asst_attr / is_show_aux_barcode	string	Auxiliary attribute flags	Critical for multi-SKU scenarios like color/size
kf_period_type	string	Shelf-life unit: 1 day 2 month 3 year	Essential for food/pharmaceutical industries
mul_label	object	Product label object/list	Complex structure, recommend JSON persistence when mapping
units	object	Multi-unit configuration	Contains conversion rates, key for cross-unit conversion

How to Configure on Qeasy Cloud

In the Qeasy Cloud data integration platform, this interface is typically invoked through the "Kingdee Cloud Xingchen V2 Adapter" wrapper. We simply select the "Material Query" action in the adapter, fill in the tenant authorization information (access_token is automatically managed), and data can be pulled directly.

For field mapping, Qeasy Cloud's field mapper automatically maps Kingdee's standard fields like id, number, name to the target table's standard columns. For complex object fields like units and mul_label, the platform provides a JSON parsing node that can expand them into detail rows with one click. For incremental sync, just check "incremental by modification time" in the scheduling configuration, and the platform automatically manages cursor watermarks without manually maintaining timestamps. Select "empty write operation" on the Target end to implement a pure query strategy, and data can be verified in real-time through Qeasy Cloud's "Data Preview" or "Log Center".

Cross-Project Practical Points

Primary keys first, build mapping table before business logic: For any cross-system integration, first run the product mapping table with id + number, then all subsequent orders and inventory sync rely on this table. In multiple customer projects, skipping this step almost always causes problems later.
Incremental + full combination: First full pull to establish baseline, then daily incremental by modify_start_time / modify_end_time. The safe approach is to keep a 7-day backtracking window to prevent missed records.
Pagination size control: Kingdee API's default page size is 20, but in practice page_size=100 gives optimal performance; setting it too high triggers rate limiting. We recommend fixing page_size=100 in Qeasy Cloud scheduling.
Object field preprocessing: Nested objects like units and mul_label should not be stored as plain strings. Be sure to expand them into detail rows or multi-value fields in Qeasy Cloud's transformer.
Null and default value fallback: Fields like barcode and help_code are often empty, so default values (such as empty string) must be set when mapping to WDT, otherwise downstream validation fails.
Off-peak batch scheduling: When Kingdee Cloud Xingchen's material volume is below the million level, running at 3:15 AM is usually fine; but if material volume exceeds one million, we recommend splitting into multiple night windows or enabling Qeasy Cloud's concurrent sharding.

Troubleshooting Retrospective

Pitfall 1: Ignoring page_size causes data loss. A customer set page_size to 50, but the actual total product count was not a multiple of 50, and the last page was not terminated with a loop check, resulting in partial material loss. The safe approach is to use the returned total field for loop termination.
Pitfall 2: Wrong millisecond timestamp unit. Kingdee's incremental parameters require milliseconds, but some engineers pass second-level timestamps, causing the incremental window to span decades and triggering a full reload. Always confirm the timestamp digit count.
Pitfall 3: Bundle products with check_type=2 not handled separately. Bundle products in WDT typically need to be split into multiple normal products. If a 1:1 mapping is applied directly, subsequent order sync will cause inventory inconsistency.
Pitfall 4: Multi-unit product units field not expanded. Kingdee's multi-unit conversion relationships are hidden in the units object. If only base_unit_name is extracted, subsequent cross-unit sales calculations will be wrong.
Pitfall 5: access_token expired without refresh. Kingdee Cloud Xingchen's token typically expires in 2 hours, so long-running batch tasks hit 401 midway. On Qeasy Cloud, the platform manages token auto-renewal, so this pitfall is essentially avoided.

When to Use

This interface is the first choice when you need to integrate WDT with Kingdee Cloud Xingchen for supply chain, or perform product master data linkage, cross-system code mapping, and product validation before order/inventory sync in e-commerce and retail scenarios. However, if the goal is only to write into Kingdee Cloud Xingchen for product creation/modification, you should use the material save interface instead; if querying inventory, use the inventory query interface. This interface only covers the master data dimension.

Authoritative Tutorial on Kingdee Cloud Xingchen Material Query Interface Field Manual (P2-173/P2-287)