Integration Design for Sales Orders Between Jushuitan and Kingdee Cloud Galaxy

Scenario and Value

E-commerce operations rely heavily on ERP-side orders, outbound documents, and return records for downstream collections, inventory, and accounting. A retail enterprise running multiple stores and channels manages online orders in Jushuitan while keeping Kingdee Cloud Galaxy as its financial and supply-chain back office. Manual data movement between the two systems causes delays, reconciliation difficulties, and inconsistencies in financial reporting.

The integration described here automatically synchronizes sales orders, outbound documents, return documents, and the associated master data (shops, customers, materials, items) from Jushuitan to Kingdee Cloud Galaxy through scheduled strategies, and pushes alerts when exceptions occur. The solution supports private deployment and remains stable under large data volumes and strict data privacy constraints.

Integration Architecture and Data Flow

The architecture consists of three layers: source systems (Jushuitan), the integration platform (Qeasy iPaaS), and target systems (Kingdee Cloud Galaxy V2). Jushuitan exposes both Qimen and non-Qimen interfaces. The Qimen channel uses start_time and end_time for incremental polling, while the non-Qimen channel uses modified_begin and modified_end. The two channels cover marketplace integrations and the enterprise's own channels respectively.

The integration platform performs three tasks: pulling source data within an incremental window and staging it; executing code mapping (shop_id → customer_number, sku_id → material_number) and field transformations (date format, order-level discount conditions); and packaging payloads according to Kingdee's API specifications. The platform also runs auxiliary strategies for token refresh, error inspection, and Feishu alerting.

Kingdee Cloud Galaxy V2 receives data through standard REST endpoints, covering sales orders, sales outbound documents, sales return documents, customers, and materials. Materials are written back to Jushuitan's item interface through a reverse strategy so that master data remains consistent on both sides.

┌─────────────────────────┐
│  Jushuitan (Qimen/non)   │
└────────────┬────────────┘
             │ incremental pull
             ▼
┌─────────────────────────┐
│  Qeasy Platform          │
│  (mapping + transform)   │
└────────────┬────────────┘
             │ write / query
             ▼
┌─────────────────────────┐
│  Kingdee Cloud Galaxy V2 │
└─────────────────────────┘

Interface List

The solution includes 15 integration strategies. They are categorized as follows:

Implementation Notes

First, master data must run first. The shop-to-customer and material-to-item strategies must execute before any business document strategy; otherwise, code mapping will fail due to missing references. The material query strategy also serves item reverse synchronization and business document validation and is recommended to run every 5 minutes.

Second, place token refresh upstream. Kingdee Cloud Galaxy access tokens have a limited lifetime. Refresh every 50 minutes between 09:00 and 21:00. When a business strategy receives a 401, call the refresh strategy first and then retry.

Third, handle the order-level discount carefully. The target field bill_dis_amount in sales outbound corresponds to free_amount in the source, but should be set to zero for reissue and exchange scenarios. This logic is implemented as a CASE expression in the transformation layer to avoid contaminating downstream accounting.

Fourth, ensure idempotency. Every write strategy uses the idCheck mechanism, deduplicating by source document numbers (order o_id, outbound io_id, aftersale as_id), so repeated pulls do not generate duplicate documents.

Fifth, handle exceptions and alerts. Kingdee API timeouts and 5xx errors are retried three times with exponential backoff (30s/60s/120s); 429 rate limiting triggers five retries at a fixed 60-second interval; business validation failures are not retried. Alerts are pushed to a Feishu group bot when a single strategy failure rate exceeds 10%, fails three times consecutively, or data latency exceeds two scheduling cycles.

Best Practices

1. Stagger schedules. Keep a clear interval between master-data strategies (query materials, query customers, shop → customer, material → item) and business document strategies to avoid concentrating calls to Kingdee APIs and to reduce the chance of rate limiting.
2. Layered logging. Persist every execution result into an integration log table with source_id, target document number, status, error message, and timestamps for later troubleshooting and reconciliation.
3. Privacy protection. Sensitive identifiers such as tenant ID and solution ID should be replaced with placeholders or masked at the configuration layer and never appear in plain text in solution documents or logs.
4. Coexistence of two channels. Qimen and non-Qimen interfaces overlap functionally but differ in field structure and incremental parameters. Build separate strategies for each during implementation to avoid missing fields caused by mixing them.
5. Dead-letter fallback. Records that fail more than a threshold number of times should be diverted to a dead-letter queue and stop automatic retries so that operations staff can intervene manually and prevent abnormal data from continuously consuming scheduling resources.