Qeasy Cloud
Get Started

Kingdee Cloud Xingchen Material Query API: The Definitive Field Handbook & Qeasy Configuration Guide

· 高金凤· Engineering Best Practices· 13 views· 4 min read
Jushuitan金蝶云星辰商品主数据供应链集成轻易云Incremental Sync字段手册

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/material with parameters modify_start_time, modify_end_time (millisecond timestamps), page, and page_size.
  • Response Structure: An outer data array containing material records with fields such as id, number, and name; pagination info is exposed via total_count.
  • Pagination / Incremental Mode: Modification-time window-based incremental pull plus standard pagination, typically combined with LAST_SYNC_TIME and CURRENT_TIME variables.
  • Detail Endpoint: /jdy/v2/bd/material_detail is used to enrich multi-unit and auxiliary attribute information.

Typical Field Mapping

FieldTypeMeaningPractical Notes
idstringInternal Xingchen primary keyUsed only inside Xingchen; use number for cross-system reconciliation
numberstringMaterial codeCore field for mapping with Jushuitan; keep globally unique
namestringMaterial nameBasis for display and reconciliation; watch for duplicates
parent_id/number/namestringParent categoryRecursively traverse when handling tree structures
base_unit_id/number/namestringBase unit of measureFoundation of UoM conversion; build a mapping table with Jushuitan
unitsobjectMulti-unit configIncludes auxiliary units and conversion ratios; must be parsed when multi-unit is enabled
is_multi_unitstringWhether multi-unit is enabledDecides whether to expand the units object
barcodestringPrimary barcodeReconcile with Jushuitan barcode field
check_typestringProduct type: 1 normal / 2 kit / 3 serviceKit products need child-item expansion
brand_id/number/namestringBrand dimensionUsed for brand-level filtering and reporting
modelstringSpecificationMap against Jushuitan spec field
help_codestringMemo codeAuxiliary field for quick search
is_serial / is_batch / is_kf_period / kf_period_typestringSerial / batch / shelf lifeDrives inventory business logic branches
is_asst_attr / is_show_aux_barcodestringAuxiliary attributesAffects SKU-level expansion
mul_labelobjectMaterial tag setSupports 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_TIME and CURRENT_TIME as built-in time variables, triggering incremental pulls on a */10 7-22 * * * schedule.
  • Field Mapper: Qeasy's field mapper automatically recognizes id and number as 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_detail for multi-unit and auxiliary attributes.

Cross-Scenario Best Practices

We have distilled the following common lessons from multiple customer projects:

  1. Code over ID: Always use number as the cross-system reconciliation key. id should only be used for internal Xingchen traceability to avoid failures from ID changes.
  2. *Timestamps Must Be 1000: The API requires millisecond timestamps. Passing seconds returns an empty set, the most common pitfall.
  3. Set page_size Between 20 and 50: Too large triggers rate limits; too small multiplies request counts.
  4. Multi-unit Objects Must Be Flattened: Raw units objects cannot perform conversion downstream; use a script node in Qeasy to flatten them.
  5. Handle check_type=2 Kits Specifically: Kits require recursive child-item expansion; otherwise outbound quantities will be incorrect.
  6. 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 units landed 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_time as 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.

Original content. Please credit the source when reposting: https://www.qeasy.cloud/insights/engineering/hb-p2-397-e1cf

Comments