Sales Return Order Sync from WMS to Kingdee: A Single-Strategy Implementation Guide
What This Strategy Solves
In one retail scenario, the e-commerce business runs on a front-end WMS while finance and supply-chain accounting live in a financial ERP. When a sales return happens, the warehouse records a return-inbound order in the front-end system, and finance needs a matching sales return document in the back-end system for receivables adjustment and inventory accounting. Manually exporting and importing between the two almost always causes quantity or amount discrepancies at month-end. This strategy automates pushing return-inbound orders into the financial ERP on a defined rule set, so each return is generated once and the two sides stay aligned.
Data Flow and Field Mapping
The flow is one-directional: Source WMS (return-inbound order) → Qeasy data integration platform (middleware) → Target financial ERP (sales return document). The middleware handles three responsibilities: field mapping, code translation, and document status validation.
The key field mapping is shown below. Code translations should be maintained centrally in the Qeasy mapping tables rather than hard-coded in scripts.
| Business Meaning | Source Field (WMS) | Target Field (ERP) | Notes |
|---|---|---|---|
| Document number | Return-inbound number | Document number | Pass-through, optional prefix |
| Customer code | Customer ID | Customer code | Lookup via customer mapping |
| Warehouse code | Warehouse ID | Receiving warehouse | Centralized mapping |
| Item code | SKU code | Material code | Material mapping |
| Return quantity | Return qty | Quantity | Direct numeric conversion |
| Unit price | Tax-inclusive price | Unit price | Reconcile tax treatment |
| Document date | Business date | Business date | Unified date format |
| Document status | Approval status | Document status | Sync only approved docs |
How to Configure on Qeasy
We deliver this pipeline with the Qeasy data integration platform. Configuration has four parts.
The first part is source extraction. In the Qeasy source node, pick the WMS connector and configure the return-inbound API, pulling approved documents by modification-time incremental. A subtle point: the incremental cursor must be the timestamp of the last successful run, otherwise records get missed or duplicated.
The second part is middleware processing. The Qeasy transform node handles field mapping, code table lookup, and null-value fallback. Centralized mapping management is a common pattern among Qeasy customers—customer, warehouse, and material mapping tables all live in one mapping center, so new stores or SKUs only require updates to the mapping tables, not the main flow.
The third part is target write. The Qeasy target node calls the financial ERP's sales-return save API. Header and body should be written in stages: write the header first to obtain the document's internal ID from the ERP, then write the body lines using that ID. Writing header and body in a single call risks leaving dirty data when some lines fail.
The fourth part is exception handling. The Qeasy exception router captures error codes from the ERP and splits traffic by error type: retryable business errors (e.g., concurrency lock) go to a retry queue; mapping-missing errors (e.g., unknown customer code) go to a human task list; system-level errors trigger immediate alerts.
Implementation Steps
We typically split the go-live into three scheduling phases.
Phase one: incremental initialization. Run a one-time full pull in Qeasy to push historically approved return-inbound orders (for example, the last three months) into the ERP as a baseline. Use the Qeasy full-trigger task with a bounded time window and mark it complete when done.
Phase two: daily incremental scheduling. A dual-track of full and incremental is a common pattern among Qeasy customers—full for initial load and periodic reconciliation, incremental for daily operations. After go-live, set the schedule to every 15 minutes, pulling by modification-time incremental, so the two sides converge quickly after a return occurs.
Phase three: reconciliation and replay. The Qeasy reconciliation node runs once overnight, comparing quantities and amounts by document number between the two systems; differences enter a task list. A replay queue processes the previous day's failed records to prevent backlog.
Pitfall Recap
Pitfall 1: Incremental cursor mishandled, first batch misses records. Using the current time as the start point caused documents approved in the minutes before the run to be missed. The safe approach is to persist the "last successful cutoff" in Qeasy so each run auto-resumes.
Pitfall 2: Tax-inclusive vs tax-exclusive price mismatch. The source system defaults to tax-inclusive price, while the target accepts tax-exclusive in some cases. Without a unified convention, daily reconciliation alarms fired constantly. We added a tax-conversion step in the Qeasy transform node and unified handling per the customer's tax configuration.
Pitfall 3: Header and body written together; partial failure leaves dirty data. A typical mistake is bundling header and body into one JSON payload. If body validation fails, the ERP rolls back, but the intermediate state is hard to trace. The fix is staged writes—only after the header succeeds do we attempt the body, and failures are re-entrant.
Pitfall 4: Missing customer mapping blocks the entire order. Temporary or test accounts in the source system were not registered in the mapping table, halting the whole flow. The improvement: in Qeasy, route "unmatched" cases to a separate human-task branch instead of interrupting the main flow.
Pitfall 5: Ignoring document status and pulling only by creation time. Draft return orders were pushed to the ERP, triggering errors on the finance side. The source-side filter must be strictly limited to approved documents, and the incremental cursor must be the approval timestamp, not the creation timestamp.
When It Applies and When It Doesn't
Applies when the e-commerce front-end ERP and the back-end finance/supply-chain ERP are separate, return volume is moderate (hundreds to a few thousand per day), and reconciliation cycles are daily. Does not apply when there are multiple e-commerce platforms with divergent return rules, complex state machines requiring branched approvals, or sub-second real-time requirements—the latter should use message-queue direct push rather than scheduled sync.