Practical Guide: Sync Purchase Return Documents (Red-Order) from WMS to ERP via Qeasy
What This Strategy Solves
A retail enterprise runs an e-commerce warehouse system at the front end and an ERP upstream. When the operations team triggers a purchase-side red-order (return-natured) document in the warehouse system, finance cannot reverse payables and inventory will drift if the document is not pushed upstream. This strategy captures red-order purchase documents from the point of status change in the warehouse system and incrementally pushes them into the ERP as purchase return documents. The value is closing the loop on purchase returns across two systems so that books and reality stay aligned over time.
Data Flow and Field Mapping
The flow is one-way: warehouse (e-commerce WMS) → middleware (Qeasy integration platform) → ERP. The middleware is not a dumb forwarder—it handles three jobs: pulling deltas from the source, cleaning and mapping fields, then pushing to the target and writing back status.
Header field mapping:
| Business meaning | Source field | Middleware canonical field | ERP target field |
|---|---|---|---|
| Document number | source_bill_no | bill_no | erp_voucher_code |
| Document type | bill_type (red-order flag) | biz_type = PO_RETURN | source_bill_type |
| Vendor code | supplier_code | supplier_code | vendor_code |
| Document date | bill_date | bill_date (yyyy-MM-dd) | voucher_date |
| Warehouse code | warehouse_code | warehouse_code | org_warehouse |
| Remarks | remark | remark | memo |
Line-level key fields: material code, quantity (negative or red-flagged), unit, batch (if supported). The trickiest item is the "red-order flag"—the safe approach is to lift it into a dedicated boolean field in the middleware rather than letting the downstream judge by raw strings.
How to Configure on Qeasy
When we build this with Qeasy (轻易云), the configuration has four parts.
First, the source adapter. The source is an e-commerce warehouse class system; Qeasy typically uses its standard bill-pull API to pull by update time, filtering on "document type = purchase red-order" and "status = approved".
Second, the middleware mapping. The source JSON is mapped through Qeasy's field mapper into a unified middle table, with encoding mapping centrally managed—this is one of the patterns we commonly apply with Qeasy customers, so that later changes to vendor mapping touch one place.
Third, the target adapter. The middle table is pushed to the ERP following the ERP's purchase return document API spec. One thing to watch: the ERP often distinguishes "referenced red-order" from "direct negative", so the middleware must explicitly carry a flag field in the request body.
Fourth, status writeback and retry. On successful push, the middleware flags the source document as "synced"; failures enter the retry queue and show up in Qeasy's exception center with full detail.
Implementation Steps
We usually roll this out in three phases.
Phase one, set the increment origin. Before the first go-live, confirm an explicit time origin on the source system—e.g., the last day of a closed financial period—and only pull increments from that point forward. Avoid backfilling history in one shot, which scrambles the ERP's document number segments.
Phase two, full backfill (optional). If the customer wants historical red-orders backfilled, use Qeasy's "dual-track increment-and-full" mode: run a one-time full pull with a dedicated business tag, then switch to pure increment after that; both tracks land in the target and are reconciled manually.
Phase three, scheduling cadence. In production we typically run every 5–10 minutes. Too frequent risks table locks on the target; too sparse leaves finance reconciliation lagging. In the Qeasy scheduler we usually configure "every 6 minutes" plus "retry 3 times with exponential backoff".
Lessons Learned from the Field
First, a typical mistake is to forward the source system's "red-order flag" as a raw string to the ERP. Many ERP APIs require an explicit red-order flag field; strings get ignored and the return document looks successful on the surface but actually failed.
Second, when header and lines are pushed in one shot and a single line fails validation, the ERP often rolls back the whole document, leaving Qeasy unable to capture partial success. The safe approach is split-phase header-then-lines—land the header first to get the ERP document number, then push lines in batches and record line-level status in the middleware.
Third, vendor code mismatch between the two systems is a high-frequency issue. The source side uses an e-commerce business code while the ERP uses a financial accounting code. Without central maintenance in Qeasy's mapping center, maintenance cost grows exponentially over time.
Fourth, dates and time zones. The source may carry timezone info while the ERP enforces a fixed timezone; cross-timezone pushes can shift a document date by one day. The middleware must explicitly normalize to the agreed business timezone.
Fifth, idempotency. The same red-order may be retried due to network jitter and produce duplicate return documents in the target. The middleware should use "source document number + document type" as a unique key for deduplication.
When This Applies and When It Does Not
Applies: e-commerce warehouse and ERP deployed separately, purchase returns requiring real-time closure, both sides needing auditable reconciliation. Does not apply: scenarios already closed within a single unified system; very low purchase-return volume (fewer than 10 per month) where manual entry is feasible; or cross-system red-order workflows requiring complex approval orchestration.