Kingdee Cloud Galaxy Master Data API Field Manual: An Authoritative Tutorial on Materials, Suppliers, and Customers
What Problem This Interface Solves
In private deployments where ERP and MES or low-code platforms coexist, materials, suppliers, and customers form the foundation of all downstream documents. In our integration projects, the core goal is to deliver Kingdee Cloud Galaxy's BD_MATERIAL, BD_Supplier, and BD_Customer master data into MES forms on JianDaoYun with unique codes, controlled status, and stable incremental syncing.
Interface Capability Overview
Authentication: On the Kingdee side, OAuth2 / Cookie login is used to obtain a token; on the JianDaoYun side, API Key + App Secret dual-factor authentication is required. In Qeasy, both connectors are pre-built; you only need to provide the instance address, account set, and tenant ID.
Request Structure: Kingdee submits FormId (document identifier) + filter conditions + field set via /syrk/interface.do or the open platform QueryExecutor; JianDaoYun writes data via /api/v1/app/{app_id}/entry/{entry_id}/data.
Response Structure: Kingdee returns Result.ResponseTime + Rows (a JSON array of field name/value pairs); JianDaoYun returns data._id and data.idCheck as the idempotency result.
Pagination/Incremental Mode: Kingdee supports time-window filtering on FModifyDate / FAuditDate / FApproveDate, with page sizes typically between 50 and 500. Incremental syncing uses these timestamps as the watermark; first-time deployment uses full sync; daily operations use incremental sync.
Typical Field Mapping
Materials (BD_MATERIAL)
| Field Name | Type | Meaning | Practical Notes |
|---|---|---|---|
| FNumber | string | Material code | Business primary key, target idCheck must be true |
| FName | string | Material name | Watch the _lName suffix in multilingual scenarios |
| FSpecification | string | Specification model | Long-text truncation is possible; evaluate target field length in advance |
| FBaseUnitId.FNumber | string | Base unit code | Nested objects must be flattened |
| FMaterialGroup.FNumber | string | Material group code | Group changes do not affect the business primary key |
| FModifyDate | datetime | Modification time | Preferred watermark for incremental sync |
| FApproveDate | datetime | Approval time | Basis for filtering approved data |
| FMATERIALID | string | Entity primary key | Used for internal dedup, not written to target |
Suppliers (BD_Supplier)
| Field Name | Type | Meaning | Practical Notes |
|---|---|---|---|
| FNumber | string | Supplier code | Business primary key |
| FName | string | Supplier name | Tax and bank info must be masked |
| FShortName | string | Short name | Used for list display |
| FTaxRegisterCode | string | Tax registration number | Sensitive field, sync with care |
| FOpenBankName / FBankCode | string | Bank name / Bank account | Bank account is highly sensitive, assess compliance |
| FPayCondition.FNumber | string | Payment term code | Nested object |
| FAuditDate | datetime | Audit time | Watermark for incremental sync |
| FUseOrgId.FNumber | string | Using organization | Multi-org requires this filter |
Customers (BD_Customer)
| Field Name | Type | Meaning | Practical Notes |
|---|---|---|---|
| FNumber | string | Customer code | Business primary key, can be reused as after-sales merchant group |
| FName | string | Customer name | Same-name customers must be distinguished via FNumber |
| FTEL | string | Contact phone | Private-domain compliance field, write with care |
| FADDRESS | string | Address | Note province/city/district splitting |
| FInvoiceTitle | string | Invoice title | Finance-related, strict validation required |
| FCustTypeId.FNumber | string | Customer category code | Nested object |
| FForbidStatus | string | Forbidden status | Only sync A (not forbidden) |
| FModifyDate | datetime | Modification time | Watermark for incremental sync |
How to Configure on Qeasy
Qeasy provides a dedicated adapter encapsulation for Kingdee Cloud Galaxy: select the Kingdee Cloud Galaxy connector, fill in the private instance address, login state, and FormId (such as BD_MATERIAL), and all fields are visible in the visual interface. The platform's field mapper automatically recognizes nested objects (like FBaseUnitId.FNumber), flattens them, and lets you drop them onto JianDaoYun target fields.
In Qeasy, this interface is typically invoked with the combination of "incremental + time watermark + business filter": set FModifyDate >= {{LAST_SYNC_TIME}} in the strategy orchestration, and add organization filters such as FUseOrgId.FNumber = '150'. After configuring Qeasy's dead-letter queue and retry policy according to Section 5, a single failure will not block the entire batch.
JianDaoYun-side configuration: select the JianDaoYun connector, pick the target app and form, enable "deduplicate by business field" (idCheck=true), and use the field corresponding to FNumber as the deduplication key.
Cross-Scenario Practical Points
- Use code, not entity ID, as the business primary key: Internal IDs like FMATERIALID change across environments and account sets; only FNumber is stable.
- Choose one of three incremental watermarks: FModifyDate has the broadest coverage, FAuditDate focuses on approved records, FApproveDate focuses on final-effective records. For multi-org scenarios, combine
FModifyDate >= LAST_SYNC_TIME OR FApproveDate >= LAST_SYNC_TIME. - Target-side idCheck must be enabled: JianDaoYun deduplication relies on business fields; without it, writes will duplicate.
- Push business filters upstream: Organization, material code prefix, and forbidden status filters must be applied on the Kingdee side rather than after sync to avoid wasted bandwidth.
- Stagger scheduling of the three strategies: Materials every 10 minutes, suppliers every 10 minutes, customers every 30 minutes, with startup times staggered by 5 minutes to avoid concentrated pressure on the target system.
- Tier sensitive fields: Bank accounts, tax registration numbers, and contact numbers are highly sensitive; in Qeasy, route them through a "masking mapper" before writing to the target.
Lessons from Real Pitfalls
- Pitfall 1: Incremental watermark drift. LAST_SYNC_TIME used system time while Kingdee returned UTC, so data was missed. The safe approach is to unify the time zone (UTC+8) in Qeasy's time format conversion node before comparison.
- Pitfall 2: Duplicate primary keys on the target side. JianDaoYun's deduplication key used
FNameinstead ofFNumber, causing conflicts for all same-named materials. Always use the code as the business primary key. - Pitfall 3: Time filter not removed in full mode. A retail enterprise's first deployment forgot to remove
FModifyDate >= LAST_SYNC_TIME, resulting in only the most recent batch being synced and historical data being lost. - Pitfall 4: Token expiry with no auto-refresh. Kingdee OAuth2 tokens expire by default after 7200 seconds; enabling "auto-refresh" in the Qeasy connector avoids a wave of 401 errors.
- Pitfall 5: Forbidden customers synced into the after-sales merchant group. A run missed the
FForbidStatus = 'A'filter, and forbidden customers appeared in the after-sales page, causing complaints.
When to Choose This Approach
This interface combination suits private deployment scenarios where ERP master data needs to be pushed to a low-code or MES platform, especially in manufacturing and retail industries where materials, suppliers, and customers require high-frequency syncing and strict code consistency. If the target side involves large transactional tables or bidirectional sync, more complex conflict detection and version control strategies are needed.