Field Handbook for Basic Data Sync Between Xiaoman OKKI CRM and Kingdee Cloud Cosmic
What This Interface Solves
In bidirectional CRM-ERP integration scenarios, Xiaoman OKKI CRM handles leads and sales order entry, while Kingdee Cloud Cosmic owns material master data and financial settlement. The goal is to push Kingdee materials to Xiaoman as product records, push CRM customers and contacts to Kingdee to establish customer master data, then flow back approved Kingdee sales orders to CRM for business closure. Typical pain points include inconsistent cross-system coding, hard-to-unify incremental logic, and contact records that depend on customer master data being in place first.
Interface Capability Overview
Authentication: Kingdee Cloud Cosmic uses OAuth2 plus application secret to exchange for an access_token; Xiaoman OKKI CRM uses API Key with signature. All credentials go into a key management service and never appear in plaintext within solution documents.
Request structure: Kingdee distinguishes documents by form_id (BD_MATERIAL, BD_Customer, SAL_SaleOrder, etc.), supports PageIndex/PageSize pagination, and uses dot notation for field paths such as FCustId.FNumber and FMaterialId.FNumber. Xiaoman splits resources by object (/v1/product, /v1/company, /v1/invoices/order, etc.), list endpoints return paginated payloads, and write endpoints are idempotent by business number.
Response structure: Kingdee returns a Result array with Status, Message, and PK; Xiaoman returns standard JSON with code, msg, and data. 5xx errors trigger retries; 4xx business validation errors go straight to the failure table.
Pagination and incremental sync: Kingdee incremental key is FModifyDate or FApproveDate; Xiaoman incremental key is order_time or start_time/end_time. Full sync removes the time filter and uses idempotent writes on the target side keyed by code.
Typical Field Mapping
Taking Kingdee material to Xiaoman product and Kingdee sales order to Xiaoman sales order as examples:
| Source Field | Target Field | Type | Meaning | Practical Notes |
|---|---|---|---|---|
| FNumber | product_no | String | Material code | Cross-system unique key, passed through as reference |
| FName | name | String | Material name | Trim leading and trailing spaces |
| FBaseUnitId.FName | cost_unit | String | Base unit | Multi-unit scenarios require separate cost/quantity/price units |
| FModifyDate | — | DateTime | Modified date | Incremental filter condition |
| FBillNo | order_no | String | Document number | Order idempotency key |
| FCustId.FNumber | company | String | Customer code | Must be joined to Xiaoman company_id |
| FDate | account_date | Date | Business date | Convert to YYYY-MM-DD |
| FExchangeRate | exchange_rate | Decimal | Exchange rate | Xiaoman uses ten-thousandths, multiply by 100 if Kingdee uses decimals |
| FMaterialId.FNumber | product_no | String | Material code | Depends on material sync completion |
| FQty | count | Decimal | Quantity | Detail line field |
| FPrice | unit_price | Decimal | Unit price | Watch precision |
How to Configure on Qeasy Cloud
On the Qeasy Cloud data integration platform, this kind of bidirectional integration is typically set up as a combination of query strategies and sync strategies. Each query strategy independently configures a source adapter (Kingdee form or Xiaoman open API) and writes to the platform data mart. Sync strategies drag-and-drop fields directly in Qeasy's field mapper, and code mappings are maintained through the Lookup Table component, which automatically performs upserts by primary key.
Qeasy Cloud ships with standard Kingdee Cloud Cosmic adapters for material, customer, sales order, and other documents—just pick the form_id and the data source is generated. Xiaoman's /v1 endpoints are connected through custom adapters. Qeasy Cloud automatically maintains the LAST_SYNC_TIME timestamp, so no manual bookkeeping is needed. Failed records flow into a dead-letter table that supports manual rerun by strategy or time window.
Cross-Solution Practical Points
- Code consistency is the key prerequisite: Material codes and customer codes must stay consistent across both systems, otherwise downstream order joins all fail. We recommend sorting out coding rules during initialization before kicking off sync.
- Contacts depend on customer master data: The Xiaoman customer to Kingdee contact strategy must wait for customer master sync to complete, otherwise contacts have no parent customer. In Qeasy Cloud, enforce the execution order via strategy dependency configuration.
- Push only approved orders for sales order sync: Kingdee sales orders are unstable before approval, so filter on FDocumentStatus='C' before syncing to avoid pushing wrong orders.
- Exchange rate and unit conversion: Kingdee exchange rate is a decimal, but Xiaoman expects ten-thousandths, so multiply by 100 during mapping. When splitting one unit field into multiple target fields, configure multi-route output in Qeasy's field mapper in one pass.
- Separate incremental and full sync: Daily runs use incremental (FModifyDate / order_time); initialization or repair uses full sync with the time filter removed. Don't mix the two modes, or you'll get missing or duplicate records.
- Tiered failure retry: 5xx and 429 use exponential backoff; 4xx business validation errors go straight to the failure table without wasting retry attempts.
Pitfall Postmortem
- Customer code mapping gaps: When Xiaoman serial_id and Kingdee FNumber rules differ, contact and order joins all fail. The safe approach is to build cross-system code lookup tables offline, run a one-time validation pass to confirm no gaps, then go live.
- Material group mapping missed: After Kingdee materials sync to Xiaoman, unmapped product groups make some products invisible in the Xiaoman frontend. In Qeasy Cloud, use the Xiaoman product group query and Kingdee material group query to generate the lookup table before writing.
- Order duplicate push: The same Kingdee order, after approval, gets synced multiple times, and because Xiaoman is not idempotent on order_no, data doubles up. The safe approach is to query by order_no before writing—update if it exists, insert otherwise.
- Salesperson mapping breaks: Kingdee salesperson code and Xiaoman nickname are inconsistent, leaving the order owner field empty. This is a common trap. We recommend running a salesperson mapping pre-warm to fill the lookup table before starting order sync.
- Throttling triggers avalanche: After Kingdee API returns 429, retry intervals are too short and cause secondary throttling. The safe approach is to fix the 429 retry interval at 60s instead of exponential backoff, to avoid crushing the source system.
When to Use
This pattern fits scenarios where CRM and ERP need bidirectional integration, customer master data is maintained in CRM, material master data is maintained in ERP, and sales orders need cross-system reconciliation. If a middle data platform already exists between the two systems, or if coding rules are completely inconsistent and cannot be aligned during initialization, we recommend doing a coding governance pass first before integration.