Integration Overview: Guanyi Cloud to Kingdee Cloud Cosmic Sales Orders

Scenario and Value

After a major e-commerce promotion, finance teams at retail companies often discover stock-sales discrepancies only three days later, while replenishment orders lag behind by half a day. The root cause is rarely the ERP itself—it is the absence of a closed loop between the front-end e-commerce ERP (Guanyi Cloud) and the back-end ERP (Kingdee Cloud Cosmic). Delivery orders and return/exchange orders circulate offline, and by the time the business notices, inventory has already been occupied for a week.

In our on-site work, the typical requirement is to sync Guanyi Cloud sales documents (delivery orders, return/exchange orders) into Kingdee Cloud Cosmic on a minute-level cadence, generating corresponding sales outbound orders and sales return orders, complemented by maintenance strategies for master data refresh, cross-solution query, and historical queue cleanup. The integration platform we use is Qeasy (轻易云 Data Integration Platform), which acts as the middle layer handling data transformation, code mapping, scheduling orchestration, and exception handling.

Integration Architecture and Data Flow

System Roles

• Guanyi Cloud · Qimen: Front-end e-commerce ERP holding the source data for delivery orders, return/exchange orders, and other sales documents.
• Kingdee Cloud Cosmic: Back-end ERP where sales outbound orders, sales return orders, and material master data are persisted.
• Integration Platform (Qeasy): Middle layer responsible for data queues, cross-solution queries, code mapping, and scheduling.

Data Flow Diagram (description)

[Guanyi Cloud · Qimen] --Strategy 1: Delivery--> [Integration Platform] --Transform/Map--> [Kingdee Cloud Cosmic: Sales Outbound]
[Guanyi Cloud · Qimen] --Strategy 2: Return/Exchange--> [Integration Platform] --Transform/Map--> [Kingdee Cloud Cosmic: Sales Return]
[Kingdee Cloud Cosmic] --Strategy 3: Query Materials--> [Integration Platform] (keeps Kingdee license active)
[Integration Platform] --Strategy 4: Cross-Solution Query--> [Integration Platform] (references other solutions on demand)
[Integration Platform] --Strategy 5: Cleanup Queue--> [Integration Platform] (deletes queues older than 3 months)

Phased Execution Order

1. Phase 1: Code Mapping Preparation—Once the material, customer, warehouse, and shop mapping tables are live, business strategies can run.
2. Phase 2: Business and Foundation—Strategies 1, 2, 3, and 4 run in parallel; Strategy 3 must remain enabled to refresh the Kingdee license.
3. Phase 3: System Maintenance—Strategy 5 cleans up historical queues during the low-traffic early-morning window to avoid storage bloat.

Interface List

Implementation Highlights

Incremental Fields and Full Backfill

• Incremental fields: Delivery orders use start_delivery_date / end_delivery_date; return/exchange orders use in_begin_time / in_end_time. Maintain the incremental window via LAST_SYNC_TIME and CURRENT_TIME.
• Full backfill: Run full sync on initial deployment or data repair; schedule outside business peak hours.

Centralized Code Mapping

All business document strategies depend on the following mappings: material (item_code/sku_code ↔ FMaterialId), customer (shop_code/vip_name ↔ FCustomerID/FRetcustId), warehouse (warehouse_code ↔ FStockId), shop (shop_code → sales org / department / owner). The reliable approach is to maintain mapping tables as standalone platform resources, with business strategies referencing them rather than redefining mappings inline.

Retry and Monitoring Thresholds

• Network timeout: exponential backoff, up to 3 retries (30s/60s/120s).
• Target system 5xx: retry 3 times with the same intervals.
• Missing code mapping: no retry, log and skip.
• Business validation failure (e.g., duplicate order number): write to dead-letter queue, no retry.
• Token expiration: trigger connector refresh then retry once immediately.

Monitoring thresholds: 3 consecutive failures pause scheduling and trigger an alert; failure rate above 10% for a single strategy requires manual investigation; dead-letter queue above 50 messages requires manual handling. Two consecutive failures on Strategy 3 deserve special attention, as they may directly affect the Kingdee license connection.

Privacy and Compliance

Mapping tables only contain business codes, not personal data. Fields such as order numbers and phone numbers in platform logs must be desensitized according to customer compliance requirements before persistence.

Best Practices and Pitfalls

1. Do not scatter code mapping across strategies. In multiple customer engagements we have seen material/customer mappings embedded in a single strategy's transformation script. When a new strategy is added, mappings get duplicated, and field misalignment is common. Centralize mappings as a platform-level resource and reference them from every business strategy.
2. Never stop Strategy 3. Many teams assume "query materials" is a throwaway maintenance task that can be paused. In practice it is the heartbeat for the Kingdee license—once stopped, subsequent real sync requests can fail in batches due to license expiration, and the failure mode is hard to spot.
3. Write header and line items in separate phases. For delivery orders, write the header first and lock the document status, then batch-write line items. This makes field validation failures on the Kingdee side easier to locate and roll back.
4. Route Qimen and non-Qimen channels separately. Guanyi Cloud exposes both Qimen and direct API channels with noticeably different field naming. We recommend wrapping both channels behind a single platform adapter and switching via configuration, avoiding duplicate business strategy development.
5. Clean historical queues regularly. Without cleanup, platform storage can grow several times over within six months, hurting query and troubleshooting performance. A nightly cleanup during the early-morning low-traffic window for data older than three months is the most cost-effective approach.

When to Use Qeasy

When there are more than two business systems, cross-ERP document sync runs more frequently than once per hour, and middleware capabilities such as code mapping, incremental windows, and retry handling are required, the maintenance cost of custom scripts quickly gets out of control. Qeasy (轻易云 Data Integration Platform) provides visual strategy orchestration, centralized code mapping management, built-in incremental/full scheduling, and dead-letter queue handling, making it suitable for normalized integration in e-commerce retail, chain distribution, and other multi-front-end ERP scenarios.