Authoritative Field Manual for Kingdee YXC "Query Brand Information" API

What This API Solves

In the supply chain integration between Jushuitan and Kingdee YXC, "brand" is a core dimension of product master data. This API (/jdy/v2/bd/material_brand) retrieves brand master data from Kingdee YXC, providing brand reference tables, mapping baselines, and validation anchors for product synchronization. Typical scenarios include brand enrichment during product sync, cross-system reconciliation, and brand hierarchy tree construction. It is a foundational piece of the master data synchronization chain.

API Capability Overview

• Authentication: Kingdee YXC Open Platform OAuth 2.0; access_token is required in headers, typically with a 2-hour validity.
• Method: GET, endpoint /jdy/v2/bd/material_brand.
• Request Parameters: modify_start_time (ms timestamp, incremental start), modify_end_time (ms timestamp, incremental end), page (default 1), page_size (default 20, ceiling depends on tenant), enable (availability flag).
• Pagination/Incremental: Supports pagination with typical page sizes of 20–100. The incremental mode relies on the modification time window, using the template variables {{LAST_SYNC_TIME}}000 and {{CURRENT_TIME}}000 to auto-compute boundaries.
• Response Structure: JSON array; each record includes brand primary key, code, name, parent brand, and extended attributes.
• Strategy Type: QUERY (read-only); the Target is configured as "Write No-Op" and does not write to any target system.

Typical Field Mapping

How to Configure on Qeasy

On the Qeasy Data Integration Platform, this API is typically exposed via a Kingdee YXC V2 adapter, eliminating the need to hand-write HTTP requests:

1. Create a QUERY strategy: Source = "Kingdee YXC V2", Target = "Write No-Op".
2. Configure the data object: Select "Material Brand"; the endpoint is auto-bound to /jdy/v2/bd/material_brand.
3. Field Mapper: Qeasy auto-loads the response fields; one-click map number → brand_code, name → brand_name, and the parent_* triplet is passed through transparently.
4. Incremental configuration: Bind modify_start_time to {{LAST_SYNC_TIME}}000 and modify_end_time to {{CURRENT_TIME}}000. Qeasy's scheduler automatically maintains the time cursor.
5. Scheduling: We recommend */10 7-21 * * *, which aligns with business hours and avoids nightly API throttling.

Cross-Strategy Practice Highlights

Drawn from multiple customer scenarios covering product sync, customer sync, and brand sync, the following lessons apply universally:

1. Use number as the business key: While id is the internal primary key, it is unstable across systems. number is the anchor for cross-platform reconciliation.
2. Brand queries must run before product sync: In the Jushuitan product synchronization chain, brand data is typically a dependency; the brand table must be ready first so that product sync can populate brand_id.
3. Don't make the incremental window too small: Kingdee's modification timestamp precision is limited; overly short windows may miss records. A 10–15 minute cadence is robust in practice.
4. autoFillResponse can bloat the field table: Template auto-fill may push material fields into the brand API's metadata. Always verify the actual response via Postman and prune irrelevant fields.
5. Persist the parent triplet together: Taking only parent_id loses context during reconciliation. Persist parent_number and parent_name together to support brand-tree validation downstream.
6. Nested objects (mul_label, units) require an expansion strategy: The field mapper must be configured with "object expansion"; otherwise downstream only receives a JSON string and cannot perform precise matching.

Pitfall Recap

1. Field duplication causes downstream conflicts: brand_id vs id, brand_name vs name may coexist in different responses, triggering unique-constraint violations on direct load. The safe approach is to add a priority rule in Qeasy's field mapper that prefers number/name/id and tags (rather than writes) duplicates.
2. Incremental window boundary loses records: On first run, LAST_SYNC_TIME is empty, which may push the full dataset into a single request and cause timeout. Run a one-time full load with enable=1 to establish a baseline, then switch to incremental.
3. Oversized page_size triggers throttling: Kingdee YXC is sensitive to response body size; page_size=500 may return HTTP 500 in some tenants. Start at 20 and scale up based on observed latency.
4. Brand hierarchy loops: parent_id may point to itself or a descendant, causing infinite loops during downstream tree construction. Add a "cycle detection" rule in Qeasy's data quality module to flag rather than write anomalous records.
5. Timestamp unit confusion: Kingdee returns milliseconds, but some legacy docs say "seconds". Without explicit unit conversion in the field mapper, the entire incremental stream is lost. Always declare unit: ms in the metadata.

When to Use

This API is intended for scenarios where you need to pull brand master data from Kingdee YXC and reconcile it with systems such as Jushuitan. Its boundary is brand-only: it does not synchronize products or customers themselves. If your goal is product master sync, pair this strategy with a product-sync strategy and run the brand table as a dependency first.