Authoritative Tutorial on the Kingdee Cloud Galaxy Material Query (with Units) API Field Handbook
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) andtotal(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
| Field | Type | Meaning | Practical Notes |
|---|---|---|---|
| id | string | Material unique identifier | Primary key, mandatory for cross-system matching |
| number | string | Material code | Main mapping key to the retail ERP SKU |
| name | string | Material name | Watch for special character escaping |
| base_unit_id / base_unit_number / base_unit_name | string | Base unit of measure | Triplet for unit mapping; build a lookup table |
| units | object | Multi-unit configuration | Contains conversion ratios; core field |
| is_multi_unit | string | Whether multi-unit is enabled | Determines if units should be parsed |
| check_type | string | Material category | 1=Normal 2=Bundle 3=Service |
| barcode | string | Primary barcode | Essential for scanning scenarios |
| is_serial / is_batch / is_kf_period | string | Serial/batch/shelf-life switches | Critical for inventory and batch integration |
| kf_period_type / kf_period | string/int | Shelf-life unit and value | 1=Day 2=Month 3=Year |
| brand_id / brand_number / brand_name | string | Brand dimension | Useful for product analytics |
| parent_id / parent_number | string | Parent category | Used to build the product hierarchy |
| price_cost_price | float | Reference cost | Reference for pricing strategy integration |
| model / help_code / remark | string | Specification/mnemonic/remark | Search 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
- Code as the master, name as auxiliary: Use
numberas the unique key for cross-system reconciliation; names are prone to whitespace and full-/half-width differences. - Build the unit mapping table first: Establish a "Kingdee unit ↔ retail ERP unit" mapping table at project kickoff to avoid downstream misalignment.
- Expand multi-units only when needed: Parse
unitsonly whenis_multi_unit=true; otherwise usebase_unit_*directly to reduce redundant writes. - Unify the incremental field: Store
last_modified_timein UTC to avoid missed records across time zones. - Route bundles through a separate flow: Items with
check_type=2should be handled by a dedicated strategy to prevent component mismatch. - Sync batch/shelf-life switches: When
is_batchoris_kf_periodis 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
unitswas 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 insideunitsresults 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_typeas int, others as string. In the field mapper, normalize to string before performing enum comparison. - Broken organization isolation: In multi-org accounts, omitting
org_idreturns 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.