Qeasy Cloud
Get Started

Authoritative Tutorial on the Kingdee Cloud Galaxy Material Query (with Units) API Field Handbook

· 谢锴斌· Engineering Best Practices· 11 views· 4 min read
Jushuitan金蝶云星辰商品主数据单位换算聚水潭集成供应链集成字段手册

What This API Solves

In supply chain integrations between a retail-style ERP and Kingdee Cloud Galaxy, product master data is the foundation for downstream inventory, order, and procurement flows. Kingdee Cloud Galaxy's material archive carries rich business dimensions including multi-units, auxiliary attributes, and shelf life. This API is designed for batch querying product master data while returning unit-of-measure information, providing an authoritative data source for cross-system SKU alignment, unit conversion, and bundle disassembly.

API Capability Overview

  • Authentication: Kingdee Cloud Galaxy Open Platform OAuth 2.0 authorization code mode. Pre-registered AppKey/AppSecret and tenant authorization are required.
  • Request Structure: HTTP POST. Input supports org_id (organization ID), page (page number), page_size (records per page), last_modified_time (incremental timestamp), and other filters.
  • Response Structure: JSON. The top level contains data (material list) and total (total count). Each item includes base fields, a units object, and extended attributes.
  • Pagination/Incremental: Supports traditional pagination and last_modified_time-based incremental pulling. Recommended page size: 100–200.

Typical Field Mapping

FieldTypeMeaningPractical Notes
idstringMaterial unique identifierPrimary key, mandatory for cross-system matching
numberstringMaterial codeMain mapping key to the retail ERP SKU
namestringMaterial nameWatch for special character escaping
base_unit_id / base_unit_number / base_unit_namestringBase unit of measureTriplet for unit mapping; build a lookup table
unitsobjectMulti-unit configurationContains conversion ratios; core field
is_multi_unitstringWhether multi-unit is enabledDetermines if units should be parsed
check_typestringMaterial category1=Normal 2=Bundle 3=Service
barcodestringPrimary barcodeEssential for scanning scenarios
is_serial / is_batch / is_kf_periodstringSerial/batch/shelf-life switchesCritical for inventory and batch integration
kf_period_type / kf_periodstring/intShelf-life unit and value1=Day 2=Month 3=Year
brand_id / brand_number / brand_namestringBrand dimensionUseful for product analytics
parent_id / parent_numberstringParent categoryUsed to build the product hierarchy
price_cost_pricefloatReference costReference for pricing strategy integration
model / help_code / remarkstringSpecification/mnemonic/remarkSearch and display aids

How to Configure on Qeasy

In the Qeasy Data Integration Platform, the Kingdee Cloud Galaxy material query API is wrapped as a visual adapter. Simply select "Kingdee Cloud Galaxy V2" as the data source and complete authorization. The platform provides a default pagination iterator and incremental timestamp manager, eliminating the need for manual loops. The field mapper automatically expands nested objects such as units into multi-row structures, which is convenient for writing to the downstream retail ERP product table. Qeasy also provides a built-in unit-mapping transformation node that compares base_unit_number against the retail ERP's unit system to perform automatic unit conversion.

Cross-Project Best Practices

  1. Code as the master, name as auxiliary: Use number as the unique key for cross-system reconciliation; names are prone to whitespace and full-/half-width differences.
  2. Build the unit mapping table first: Establish a "Kingdee unit ↔ retail ERP unit" mapping table at project kickoff to avoid downstream misalignment.
  3. Expand multi-units only when needed: Parse units only when is_multi_unit=true; otherwise use base_unit_* directly to reduce redundant writes.
  4. Unify the incremental field: Store last_modified_time in UTC to avoid missed records across time zones.
  5. Route bundles through a separate flow: Items with check_type=2 should be handled by a dedicated strategy to prevent component mismatch.
  6. Sync batch/shelf-life switches: When is_batch or is_kf_period is enabled upstream, the downstream inventory module must also enable corresponding capabilities to avoid stock freezing anomalies.

Pitfall Retrospective

  • Lost unit conversion ratio: In one retail integration, only the base unit was synced while the conversion ratio in units was ignored, causing the downstream system to price whole-box shipments by piece. The safe approach is to deliver all multi-unit fields in full and persist the conversion ratio in a custom field.
  • Inconsistent incremental timestamp format: Kingdee returns local time strings while the retail ERP writes UTC timestamps. This is where things tend to go wrong. A normalization step in the middleware is mandatory.
  • Empty bundle components: When check_type=2, a missing components array inside units results in "empty SKUs" downstream. In Qeasy, add a fallback rule that skips empty arrays and raises an alert.
  • Field type mismatch on material category: Some Kingdee versions return check_type as int, others as string. In the field mapper, normalize to string before performing enum comparison.
  • Broken organization isolation: In multi-org accounts, omitting org_id returns materials from all organizations, leading to unauthorized syncing. Always pass the parameter explicitly.

When to Use

This API is suitable for material master data initialization and daily synchronization in two-way "retail ERP ↔ Kingdee Cloud Galaxy" supply chain integrations, especially where unit conversion, bundle disassembly, and batch/shelf-life synchronization are required. For lightweight integrations involving only order data with no unit conversion needs, calling the order API directly is preferable—no need to introduce full material master synchronization.

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

Comments