Overview of Basic Data Integration Solution for Jushuitan and Kingdee Cloud Xingchen
Scenario and Value
After an e-commerce promotion season, a retail enterprise found that the inventory in Jushuitan did not match the book inventory in Kingdee Cloud Xingchen. Hot-selling items were out of stock, but purchase replenishment had not been recorded in time. The problem was not slow single-side reporting, but the lack of an automatic closed loop between the two systems: Kingdee had already deducted inventory while Jushuitan's stock count remained at yesterday's level. Inconsistent basic data causes subsequent purchase orders, sales orders, and inbound/outbound orders to misalign.
In an actual project, we encountered a similar chain retail customer. Jushuitan served as the front-end ERP for store management, demand requests, and e-commerce fulfillment. Kingdee Cloud Xingchen served as the back-end financial ERP for general ledger, book inventory, and purchase settlement. Both systems ran independent product, warehouse, and employee codes, with manual mapping tables that drifted by dozens to hundreds of records per month.
This solution focuses on the "basic data" layer. It first aligns product master data, product categories, warehouses, employees, and units, then drives check count documents (inventory coverage) into Jushuitan to achieve book-to-physical inventory synchronization. Specific goals include:
- Product master data synchronized one-way from Kingdee Cloud Xingchen to Jushuitan, with unified SKU codes.
- Product category, warehouse, and employee codes centralized in a mapping table; business documents land according to the mapping.
- Inventory split by warehouse dimension into check count documents for real-time inventory reconciliation.
Integration Architecture and Data Flow
The overall architecture is organized sequentially into three stages: "Authentication → Basic Data Query → Business Document Sync."
- Authentication Stage: The platform refreshes the Kingdee Cloud Xingchen Token on a schedule or upon expiration. All subsequent calls depend on this Token.
- Basic Data Query Stage: Four types of data (product categories, products with units, warehouses, and employees) are pulled in parallel and stored in the platform-side code mapping table. This step must complete before business document sync; otherwise, downstream sync fails due to missing codes.
- Business Document Sync Stage: Product master data is synchronized to Jushuitan incrementally or in full. Real-time inventory is split by warehouse dimension into check count documents and pushed to Jushuitan.
Data flow described by stage:
- Kingdee Cloud Xingchen → Jushuitan: Product master data (Kingdee material → Jushuitan product), inventory (real-time inventory → check count document).
- Kingdee Cloud Xingchen → Platform: Query results for product categories, products (with units), warehouses, and employees, used to build mappings between id/name and Jushuitan internal codes.
- Platform Internal: Token refresh and centralized code mapping management. This is where the Qeasy data integration platform (轻易云数据集成平台) excels—unifying scattered query results into a reusable mapping table.
In terms of dependencies, product sync depends on the category mapping being ready first. Check count sync depends on both product sync (to ensure sku_id consistency) and the warehouse mapping (for splitting documents by warehouse).
Interface List
| Strategy ID | Data Object | Sync Direction | Notes |
|---|---|---|---|
| 1 | Get Latest Xingchen Authorization | INTERNAL | Token/credential refresh; prerequisite for all Kingdee APIs |
| 2 | Query Kingdee Xingchen Employees | B → PLATFORM | Build mapping between employee id/number and Jushuitan operator/handler |
| 3 | Kingdee Xingchen Products → Jushuitan Products | B → A | Depends on Strategy 4; number → sku_id |
| 4 | Query Kingdee Xingchen Product Categories | B → PLATFORM | parent_id → c_name join query |
| 5 | Query Kingdee Xingchen Products (Get Units) | B → PLATFORM | Build base_unit_name → unit mapping |
| 6 | Kingdee Xingchen Product Inventory → Jushuitan Check Count | B → A | Depends on Strategy 3, 7; split by warehouse |
| 7 | Query Kingdee Xingchen Warehouses | B → PLATFORM | stock_number → warehouse mapping (1/2/3/4) |
Note: B = Kingdee Cloud Xingchen, A = Jushuitan, PLATFORM = integration platform side.
Implementation Points
Staged Scheduling. Authentication and query strategies run every 20 minutes during the 7-23 time window. Product sync runs every 30 minutes. Check count sync runs most frequently, every 5-10 minutes. Full reconciliation is recommended during weekly business off-peak hours, e.g., early Sunday morning, pulling all records by omitting timestamps or using a large time window to correct any incremental omissions.
Incremental Fields and Full Reconciliation. Daily sync uses incrementals (by last-modified time). Weekly full reconciliation serves as a fallback. Full strategies can reuse the query strategy APIs with different parameters and time windows.
Centralized Code Mapping Management. Five types of mappings—product codes, category codes, warehouse codes, employee codes, and unit codes—are uniformly stored in the platform-side mapping table. Product sync uses number → sku_id. Check count uses material_number → items.sku_id and stock_number → warehouse (main warehouse=1, sales return warehouse=2, purchase warehouse=3, defective warehouse=4). Missing mappings trigger alerts without blocking other data.
Exception Retry and Failure Handling. Network or API timeouts use exponential backoff retry 3 times (30s, 60s, 120s). Rate limiting 429 uses linear backoff 5 times. Single record failures are written to the failure queue without blocking subsequent batches. Alerts trigger when the same strategy fails ≥5 consecutive times or queue backlog exceeds 1000. For authorization expiration, retry once after refresh; if refresh fails, alert immediately.
Check Count Splitting and Unmapped Product Handling. Check count documents are split by warehouse dimension for submission. Single warehouse failures do not affect other warehouses. When product codes are not mapped, skip that detail line and alert, rather than rolling back the entire document.
Privacy and Credential Security. All Tokens and API Keys are encrypted on the platform side, logs are desensitized, and the principle of least privilege is followed.
Best Practices and Pitfall Reviews
- Never assemble code mappings inline within business strategies. Early on, we saw product sync strategies perform inline category queries, and when the category API wobbled, it dragged down product sync. The stable approach is to centralize all code mappings in the platform-side mapping table, with business strategies only handling field transport. The mapping center of the Qeasy data integration platform (轻易云) is designed for this scenario—one-time pull of category, product, warehouse, and employee mappings for long-term reuse.
- Split check count documents by warehouse; do not push all at once. Submitting all warehouse check details at once means any single warehouse error causes the entire document to be rejected by Jushuitan. After splitting by warehouse, single warehouse failures can be retried individually with minimal business impact.
- Schedule full reconciliation weekly. Even the steadiest incrementals miss things. Bulk price changes or category modifications can slip past timestamps. A weekly full reconciliation catches these cases; schedule it during business off-peak hours.
- Token refresh should not rely solely on scheduling. Refreshing Tokens only after expiration causes the first batch of calls to fail entirely. The stable approach is "trigger on expiration + scheduled fallback," actively refreshing every 2 hours.
- The c_name field for category join queries should be nullable. The parent_id of Kingdee materials in some historical data has no corresponding category. Leaving c_name empty is safer than forcing a default value, allowing business users to immediately identify which products need category supplementation.
When to Use Qeasy
If your project involves basic data sync between multiple ERPs, e-commerce ERPs, and financial ERPs, with code mappings scattered across multiple manually maintained Excel files, the Qeasy data integration platform (轻易云) packages authorization refresh, code mapping, exception retry, and staged scheduling into out-of-the-box capabilities. The 7 strategies can be wired up in the console and run end-to-end, suitable for near real-time basic data alignment in medium-to-large retail, e-commerce, and trading enterprises.