Authoritative Tutorial on Kingdee YXC Material Group Query Interface: A Jushuitan Integration Perspective

What Problem Does This Interface Solve

In retail ERP integration, product categories are one of the two pillars of product master data. When we integrate Jushuitan with Kingdee YXC, category mapping usually precedes the products themselves—without aligned categories, SKU sync cannot proceed. The /jdy/v2/bd/material_group interface is designed to fetch Kingdee YXC material groups (product categories) in paged batches by modification time. It supports incremental queries and tree-level identification, making it the prerequisite for building category mapping tables, initializing category systems, and downstream product synchronization.

Interface Capability Overview

• Authentication: Standard OAuth/app authorization for Kingdee YXC V2 WebAPI; an access token must first be obtained via an authorization strategy.
• Request Structure: GET request to /jdy/v2/bd/material_group, supporting time-window filtering (modify_start_time, modify_end_time, format yyyy-MM-dd HH:mm:ss) and pagination parameters (page defaults to 1, page_size defaults to 50; recommended 100-200 to reduce request count).
• Response Structure: Returns a JSON array where each record is a category; fields are flattened in data[], with primary key id and code number annotated separately in metadata.
• Detail Interface: /jdy/v2/bd/material_group_detail retrieves a single record by id, commonly used for troubleshooting field meanings.
• Pagination & Incremental: Standard page-based pagination; incremental relies on modify_start_time / modify_end_time timestamps; the typical schedule is every 5 minutes from 08:00 to 20:00 (*/5 8-20 * * *).
• Strategy Type: Pure QUERY (no-op write), the target does not persist data; it serves only as a mapping data source for other write strategies.

Typical Field Mappings

How to Configure on Qeasy (Qingyiyun)

On the Qeasy Data Integration Platform, this interface is typically wrapped as the "Kingdee YXC Adapter": select Kingdee.YXC / bd.material_group in the source system component, and the platform automatically injects the authorization header and paginator. modify_start_time defaults to the cutoff of the last successful call—no manual cursor maintenance needed.

The Field Mapper automatically exposes id / number / name / level / is_leaf as standard output columns. If the target is Jushuitan, you can drag them directly onto the "Product Category" target fields on the visual canvas. Setting Target to "Write No-Op" means this is a pure query strategy—data only lands in Qeasy's staging table, available for subsequent write strategies (such as "Kingdee YXC Products → Jushuitan Products") to reference by id.

For scheduling, we recommend crontab set to */5 8-20 * * *, staggered from upstream product write strategies to avoid collisions between token refresh and bulk queries.

Cross-Project Practical Insights

1. Retain both id and number: id is stable but not human-readable across systems; number is readable but may be adjusted by ops. Keeping both is safest.
2. Don't max out pagination: Kingdee YXC V2 occasionally times out above 200 records per page; in real scenarios we usually set page_size to 100.
3. Allow overlap in incremental time windows: Each round's modify_start_time should be 1-2 minutes earlier than the previous round's cutoff to prevent edge records from being missed.
4. Drive tree traversal by is_leaf: Don't rely on level values to determine whether there are children—level depth can be non-contiguous; is_leaf is more reliable.
5. Authorization first: Across projects, "Fetch Latest YXC Authorization" is consistently positioned as sequence=A, with subsequent queries depending on its output token—always schedule it first.
6. Declare dependencies explicitly: Product write strategies typically depend on category queries; otherwise, "products written before categories arrive" dirty data will occur.

Pitfall Recap

• Easy to crash here—merging duplicate-named categories: Two categories with different id but same name were wrongly treated as the same record, causing downstream Jushuitan categories to be overwritten. The safe approach is to always use id as the reconciliation key.
• Timezone drift: A common cause of missed incremental records is inconsistent timezones between Kingdee's returned modify_time and Qeasy's incoming modify_start_time; always unify to Beijing time.
• is_leaf case-sensitivity trap: In one client project, Kingdee's bulk interface returned capitalized True/False, causing direct string comparison to fail—always normalize with str(...).lower().
• Silent failure on token expiration: tokens expire by default in 2 hours; if the authorization strategy does not run before the query strategy, queries receive 401 but Qeasy does not retry by default—the authorization strategy must be included in the DAG dependency.
• Rate limiting triggered by large page_size: A retail client once set page_size to 500, triggering QPS throttling on the Kingdee side and stalling the entire batch task. Returning to 100 stabilized the run.

When to Use This

This interface suits "category-first" retail ERP integration scenarios—for example, a retail enterprise that uses Kingdee YXC as the product master data center and Jushuitan as the front-end store system, for both initialization and daily sync. It is not suitable for scenarios requiring category writes—this is a pure query interface; to write back to Kingdee, use the save interface with matching authorization and field mappings.