Sales Return Order Sync in Practice: From WDT Return Notice to Kingdee Cloud Skyline Sales Return Order
What This Strategy Solves
Retail stores generate large volumes of offline returns every day. In the WDT·Enterprise Edition, these returns are first recorded as "return notices"; finance and supply chain teams then need to post them as "sales return orders" in Kingdee Cloud Skyline to settle accounts, reverse costs, and adjust inventory and receivables. The two systems use different data models—field names, organizations, customers, warehouses, and batch rules all differ—and manual re-entry is slow and error-prone. On a customer site, we used the Qeasy data integration platform to handle this strategy, with the goal of pushing return notices into Kingdee as sales return orders in an automated, traceable, and replayable way, so stores can focus on registration while accounting and inventory are handled by the system.
Data Flow and Field Mapping
The flow is unidirectional: WDT·Enterprise Edition (return notice) → Qeasy middleware (adapters, transformations, validations) → Kingdee Cloud Skyline (sales return order).
Key field mapping (typical):
| Business meaning | WDT·Enterprise Edition · Return notice | Kingdee Cloud Skyline · Sales return order | Notes |
|---|---|---|---|
| Document number | Return notice number | Document number (FBillNo) | Source ID written back for traceability |
| Document date | Return date | Business date | Time zone follows source system |
| Customer | Store code | Customer code | Handled via centralized code mapping |
| Warehouse | Return-to warehouse | Receiving warehouse | Org isolation mapped per store |
| Item code | SKU code | Material code | Depends on master data being in place first |
| Quantity | Return quantity | Actual return quantity | Units of measure must align |
| Return reason | Remark | Remark / reason code | Long text may be truncated |
| Source document | Original sales order number | Source type + source number | Used for linked generation |
Centralized code mapping is a common pattern among Qeasy customers: separate mapping tables for customer, warehouse, and item codes are maintained independently, so adding new stores or SKUs only requires updating the mapping without touching the main flow script.
How to Configure It on Qeasy
On the Qeasy data integration platform, this strategy is typically split into three nodes: a source data source (WDT·Enterprise Edition open API), an intermediate transformation, and a target data source (Kingdee Cloud Skyline WebAPI / document save API).
Typical configuration points:
- Data sources: Pull from WDT using "return notice + document status + modification time"; after saving the sales return order in Kingdee, write the document number back to the source.
- Filters: Only fetch notices that are "approved" to avoid draft-state pollution downstream; apply org isolation per store.
- Field mapping: In the Qeasy transformation node, split header and body fields—header holds document-level fields (customer, date, warehouse) and body holds line items (item, quantity, unit price). Phased header-then-body processing is a common Qeasy customer practice: create the header first, get the internal document ID returned by Kingdee, then write the body line by line, so errors are easy to locate.
- Code mapping: Customer, warehouse, and item codes go through a centralized mapping table; adding entries does not require modifying the main flow.
- Write-back and reconciliation: After the Kingdee document is successfully created, write the document number back to a custom field on the original WDT record to support bidirectional reconciliation.
- Exception handling: Failed rows go into a retry queue and can be alerted on by error category (required fields, missing codes, insufficient inventory).
Implementation Steps
On customer sites we usually proceed in three phases:
Phase 1: Full initial load At first go-live, manually trigger a full load in Qeasy to push all historically approved return notices into Kingdee at once. The full-load phase does not depend on an incremental cursor; it pulls in batches by document-date range, with each batch controlled at a few hundred to a thousand documents to avoid instantaneous pressure on the downstream.
Phase 2: Incremental start-point switchover After the full load completes, switch the cursor to "last successful time" and enter incremental mode. The incremental start point is usually either the max business date on the Kingdee side + 1, or the last-modified timestamp on the WDT side; both approaches require a reconciliation pass at the switchover to confirm no gaps.
Phase 3: Steady-state scheduling Run incremental and full loads on dual tracks: incremental runs every 5–15 minutes during off-peak hours to keep up with new returns; full load runs as a reconciliation task during the early-morning off-peak window, catching missed or replayed documents. The Qeasy scheduler can run both plans in parallel, with dependencies strung between strategies—for example, this sales return order strategy depends on upstream item master and customer master syncs running successfully first.
Lessons Learned from the Field
- Code mapping scattered across scripts: In an early integration, customer and warehouse codes were written directly into transformation scripts, so adding a new store later required modifying the main flow. The safe approach is to maintain a centralized mapping table in Qeasy—new stores only update the table, not the flow.
- Submitting header and body in one shot: Kingdee's sales-return-order save API requires the header to exist before the body can be written; submitting everything at once easily produces "header succeeded but body failed" dirty data. Phased submission makes errors easier to locate and easier to retry.
- Wrong cursor for incremental start: Using "created time" as the incremental cursor causes documents delayed in approval to be missed; the correct approach is to use "last modified time" or the max business date on the Kingdee side, and to perform an explicit reconciliation at switchover.
- Long-text truncation of return reasons: WDT return remarks are long-form text, while Kingdee remark fields have length limits. This is where things often go wrong—syncing directly will fail; the safe approach is to truncate at the front end or store the value in a custom field.
- Org isolation not configured: Retail enterprises often span multiple stores and legal entities; warehouses and customers must be mapped per organization, otherwise documents end up under the wrong legal entity, and cleaning up afterwards is expensive.
Applicable and Non-applicable Scenarios
Applicable: Retail and chain-store operations with offline return processes that need to push return notices from a front-end ERP/OMS into a back-end financial ERP as sales return orders for accounting, inventory, and receivables reversal.
Not applicable: Pure online e-commerce returns (which follow platform refund flows rather than offline return notices); cross-entity returns that require inter-organization settlement first; and initial environments without upstream master data (items, customers) in place.