Return Order Sync from E-Commerce Mid-Platform to ERP: A Single-Strategy Playbook for Wangdiantong → Kingdee Cloud Cosmic
What This Strategy Solves
Return order handling is a classic "data backflow" pattern in retail: after-sales return orders from the e-commerce mid-platform must flow back into the ERP as formal sales return orders, driving inventory reduction, receivables reversal, and financial accounting. It looks like "pushing the same document in reverse," but in practice it involves document type conversion, return/exchange flag handling, and differences between whole-document and split-warehouse inventory. This article focuses on a single strategy: writing return orders generated in Wangdiantong into Kingdee Cloud Cosmic as sales return documents, with both header and line structure preserved.
We deliver this kind of synchronization using the Qeasy Data Integration Platform. The typical pattern we see across customer sites is "centralized encoding mapping + header/line staged mapping + dual-track incremental and full-load," which ensures a clean first-time landing and stable incremental runs thereafter.
Data Flow and Field Mapping
The overall direction is: Wangdiantong (source) → Qeasy middle layer → Kingdee Cloud Cosmic sales order (target). Qeasy handles protocol adaptation, field mapping, and exception staging.
Key field mapping (excerpt):
| Business Meaning | Wangdiantong Source (Return) | Kingdee Cloud Cosmic Target (Sales Order – Return) | Handling Notes |
|---|---|---|---|
| Document Number | return_no | FBillNo | Unique in source; rewritten per target encoding rules |
| Document Type | return_type | FBillTypeID | Maintained centrally in Qeasy mapping table |
| Return Flag | return_flag | FReturnType / FHeadExchangeTypeId | Must be clearly distinguished from exchange |
| Customer Code | customer_code | FCustId | Depends on the upstream "customer" strategy |
| Warehouse Code | warehouse_code | FStockId | Split-warehouse lines must be converted per line |
| SKU Code | sku_code | FMaterialId | Depends on the upstream "material" strategy |
| Return Quantity | qty | FQty | Take absolute value |
| Tax-Inclusive Price | price | FTaxPrice | Precision follows target requirements |
| Tax Amount | tax | FTaxAmount | Handle rounding carefully |
In terms of dependencies, both materials and customers belong to upstream "master data synchronization" strategies and must complete first before document synchronization can begin.
How to Configure in Qeasy
Configuring this strategy in Qeasy comes down to three things: the source fetch API, the target write API, and the field mapping and transformation scripts.
- Source configuration: Connect to Wangdiantong's open API to retrieve the return order list (incremental by update time), then pull details (including line entries) by document number.
- Target configuration: Use Kingdee Cloud Cosmic's standard API to write into "Sales Order," using the preset code for the "Return" document type.
- Mapping and transformation: Maintain encoding mappings for customer, warehouse, and material in Qeasy's "Encoding Mapping" module; map header and body in two separate segments to avoid oversized, hard-to-maintain single configurations.
- Validation and staging: Pre-validate required fields, lengths, and numeric ranges; write failed records to the Qeasy staging table, manually complete them, and replay — never block the main flow directly.
- Logging and alerts: Enable field-level logs for precise row-level diagnostics; classify sync failures by error code with tiered alerts, sending SMS to on-duty staff for business-critical errors.
Implementation Steps
We recommend a four-phase rollout to avoid being overwhelmed by unknowns at go-live.
Phase 1: Master data preparation Run the three upstream strategies (material, customer, warehouse) first to ensure the target side has a complete ID master. Without this, every subsequent document will fail because the master cannot be found.
Phase 2: Full-load initialization Use return orders from the past month for full retrospective loading. Manually trigger a full-load task in Qeasy, writing document by document. The focus of this phase is observing whether the field mapping is complete and whether special documents (such as gift returns or bundle returns) can be converted correctly.
Phase 3: Incremental scheduling go-live Set cron schedules based on business cadence — for retail stores, every 15-30 minutes; during e-commerce promotions, shorten to every 5 minutes. Set the incremental starting point to the timestamp when the full load completes, ensuring no duplicates or omissions.
Phase 4: Steady-state operations and reconciliation Configure a daily reconciliation job in Qeasy: Wangdiantong-side return order amount total vs. Kingdee-side return order amount total — if the difference exceeds the threshold, automatically trigger an alert. Only after this phase is the strategy truly considered live.
Pitfalls and Lessons Learned
- Return/exchange flags not separated: Many teams trip on this during first launch — returns and exchanges share the same API, but the target document type and accounting subjects are completely different. The safe approach is to enforce strict validation on
return_flagin Qeasy; any non-conforming record goes to staging. - Split-warehouse lines flattened: If a Wangdiantong return order has different source and return warehouses, it gets flattened into a single line, causing inventory to be written off at the wrong location. Handle line-by-line in mapping; do not aggregate in scripts.
- Incremental start point set incorrectly: After full-load completion, forgetting to align the incremental start point to the full-load end time causes a batch of historical documents to be replayed. The safe approach is to use the full-load task's end timestamp as the incremental
start_time. - Dependency strategy order mismatch: Starting document pushing before materials and customers are complete results in mass failures. Use Qeasy's strategy orchestration to chain "master data synchronization" and "sales order synchronization" together.
- Vouchers and documents out of sync: After a return order is synchronized, finance staff need to manually generate red-letter invoices or reversal vouchers afterward. Consider making this an optional "next-hop" strategy in Qeasy to avoid lengthening the main flow.
Suitable and Unsuitable Scenarios
Suitable: Retail chains, brand e-commerce, and cross-border trade scenarios that have after-sales return operations and need to backflow e-commerce mid-platform return data into the ERP for financial and inventory closure.
Unsuitable: B2B work-order-style returns and exchanges, small-amount refund differences that do not need to enter the ERP financial flow, and special scenarios requiring direct document type changes on the source side. Such requirements should go through a separate work-order flow rather than a synchronization flow.