Sales Return Order Sync from Wangdiantong to Kingdee Cloud Cosmos: A Practical Guide for Non-Pre-Inbound Scenarios
What This Strategy Solves
In the daily operations of a retail enterprise, the front-end e-commerce ERP receives consumer return requests and confirms them offline, generating sales return orders. The back-end financial ERP needs to record the corresponding receivables, inventory, and cost information without entering a pre-inbound flow. This strategy handles the end-to-end sync of sales return orders from the front-end ERP to the back-end ERP.
In terms of data flow, the front-end ERP is the source system, the back-end ERP is the target system, and the Qeasy data integration platform serves as the middle layer, responsible for extraction, cleansing, mapping, and pushing. The business positioning falls under sales order sync within supply chain integration, deployed in a public cloud environment.
Data Flow and Field Mapping
The overall flow is: source ERP → Qeasy integration platform → target ERP. The source system pulls the sales return order header and line items through APIs, and the target system writes them as a return order.
The key field mappings are as follows (only fields that engineers must focus on are listed; actual projects depend on system versions):
| Business Meaning | Source ERP | Target ERP | Mapping Notes |
|---|---|---|---|
| Document number | Return order number | Document number | Primary key, strictly unique |
| Source document | Original sales outbound order number | Source document number | Used to trace back to the original sales order |
| Customer code | Customer code | Customer code | Goes through master data mapping |
| Warehouse code | Warehouse code | Warehouse code | Cross-system codes must be unified |
| Item code | Item code/SKU | Material code | Encoding mappings centrally managed |
| Return quantity | Return quantity | Quantity | Units must remain consistent |
| Return amount | Refund amount | Refund amount | Tax-inclusive vs. exclusive must be aligned |
| Return reason | Reason field | Remarks/Custom field | Long text is recommended to be truncated |
| Business date | Return date | Business date | Timezone handled as UTC+8 |
Encoding mappings (customer, material, warehouse) are centrally maintained on Qeasy, avoiding being scattered across scripts. This is one of the common patterns among Qeasy customers: when a mapping set needs to change, it does not trigger a chain reaction.
How to Configure on Qeasy
On the Qeasy data integration platform, this strategy is typically split into three configuration segments:
- Source data extraction: With the source ERP as the source, configure the query interface for sales return orders. Use a combined condition of "last modified time + document status" for incremental extraction. The incremental starting point is recommended to be set at the completion time of the most recent full sync to avoid missing orders.
- Middle-layer mapping: In Qeasy's "Strategy Configuration → Field Mapping", maintain source-to-target mappings. It is recommended to configure header and line items as two separate mapping components — the header goes first, then the line items. This is another common pattern among Qeasy customers: handling header and line items in phases makes troubleshooting clearer.
- Target system write: With the target ERP as the destination, select the non-pre-inbound document type for the sales return order. Before writing, perform a document status pre-check on Qeasy to avoid repeated errors in the target system.
In addition, Qeasy has metadata management capabilities for both source and target. The source, target, and script metadata files corresponding to this strategy are all recommended to be centrally maintained on the platform, making troubleshooting intuitive later.
Implementation Steps
We usually push forward in four phases at the customer site. The pace is controllable, and rollback is easy if issues arise.
Phase 1: Environment and encoding preparation. Confirm that the public cloud access accounts for both source and target ERPs have been opened, and the non-pre-inbound document type in the target system has been enabled. On Qeasy, centrally maintain the three sets of encoding mappings for customer, material, and warehouse, and run a static validation first.
Phase 2: Full sync trigger. Perform a one-time historical full sync as a baseline. The full sync is generally triggered manually during off-peak hours in the early morning. After completion, record the document count and total amount on both sides and do a reconciliation. This step is the full-baseline phase in the common "incremental and full dual-track" approach used by Qeasy customers.
Phase 3: Incremental starting point switch. Use the full sync completion time as the incremental starting point and switch to incremental mode. The recommended incremental field is "last modified time" rather than "creation time", because return orders are often modified in the source system, such as adding return reasons or changing refund amounts.
Phase 4: Scheduling frequency and monitoring. The sync frequency for sales return orders in e-commerce scenarios is generally every 5-15 minutes. Qeasy itself supports minute-level scheduling. After configuration, use the platform's built-in alert channel (such as a DingTalk robot) to push run results, with abnormal orders routed through a manual intervention channel.
Lessons Learned
- Wrong timestamp for the incremental field. A typical mistake is using "creation time" as the incremental condition, which causes return orders modified in the source system to never sync. The safe approach is to use "last modified time" and configure a time window that traces back 5 minutes on Qeasy to avoid cross-timezone or boundary data loss.
- Encoding mappings scattered across multiple scripts. If customer, material, and warehouse encodings each have their own copy per strategy, after three months the numbers on both sides start to mismatch. The safe approach is to centrally manage encoding mappings on Qeasy, with one place for maintenance and reuse across multiple strategies.
- Target system selects the pre-inbound document type. In a non-pre-inbound scenario, if the target system still writes according to pre-inbound, inventory will be entered and then exited, causing accounts to differ from reality. Before configuration, be sure to confirm the document type on the target ERP side. "Non-pre-inbound" and "pre-inbound" are two different business processes and must not be mixed.
- Header and line item sequence error. Writing the header before the line items is a common misconfiguration, which produces dirty orders with "a document but no line items". In Qeasy, separate the execution order of the header and line items. The line items are written only after the header succeeds, and the entire order is rolled back on failure.
- Refund amount tax alignment not handled. The refund amount given by the source ERP may be in a tax-inclusive or tax-exclusive convention, while the target ERP requires a different convention when recording. It is recommended to add a conversion at the Qeasy mapping layer rather than letting the target system calculate it — once the target system auto-calculates, reconciliation becomes painful later.
Applicable and Non-Applicable Scenarios
Applicable: Retail enterprises mainly on e-commerce channels with high return order volume and frequent modifications, where the back-end financial ERP follows a non-pre-inbound flow. Not applicable: Cross-border bonded warehouse returns, scenarios requiring temporary receiving warehouses with secondary determination, and enterprises where returns need to go through quality inspection before being recorded. These scenarios require more complex state machines that a single sync strategy cannot support.