Practical Guide: Syncing After-Sales Orders from a SaaS WMS to a Red-Invoice Sales Order in an On-Prem ERP
What This Strategy Solves
In a retail business, after-sales returns originate as after-sales documents in a cloud-based e-commerce warehouse management system (in the form of a SaaS WMS like the source platform) and must be written back into the on-premise financial ERP (in the form of an ERP like the target platform) as red-invoice sales orders to reverse the corresponding revenue. Although this link seems simple, it is the most error-prone in practice: the direction is a write-back rather than a push-down, the red-invoice flag must be stable, and the state machine of an after-sales document differs from that of a regular sales order. By using Qeasy (轻易云数据集成平台) to host this flow, field mapping, scheduling policy, and exception handling can be encapsulated into a single strategy, avoiding semantic drift caused by stitching multiple tools together.
Data Flow and Field Mapping
The overall flow is: source after-sales order → Qeasy middleware layer (encoding mapping, field normalization, state judgment) → target red-invoice sales order.
Key field comparison (typical semantics; actual values depend on each side's interface dictionary):
| Business Meaning | Source After-Sales Field (Example) | Middleware Handling | Target Red-Invoice Sales Order Field |
|---|---|---|---|
| Document Number | source_bill_no | Pass through directly | Business document number |
| Document Date | source_bill_date | Normalize to yyyy-MM-dd | Document date |
| Red-invoice flag | — | Middleware forces value to 1 (strategy convention) | Red-invoice flag |
| Warehouse code | source_warehouse_code | Encoding mapping table (centrally managed) | Warehouse code |
| Item code | source_sku | Encoding mapping table (centrally managed) | Inventory code |
| Quantity | qty | Sign not flipped, quantity is positive, red-invoice flag distinguishes | Quantity |
| Tax-inclusive price | tax_price | Pass through directly | Tax-inclusive price |
| Tax amount | tax_amount | Pass through directly | Tax amount |
| Customer code | customer_code | Encoding mapping table | Customer code |
| Remarks | remark | Append source identifier such as "after-sales write-back" | Remarks |
A common practice here is to split the header and body into two stages: the header (document number, customer, date, red-invoice flag) first enters the target system through the document header interface, and then the body (line items, warehouse, inventory, quantity, price) is looped through the document body interface. The two stages are correlated by the source document number to prevent lost or duplicated line items.
How to Configure on Qeasy
In the Qeasy data integration platform, create a new data integration solution, with the source side selecting the after-sales document and the target side selecting the red-invoice sales order. Key configuration points:
- Data source registration: Configure source system authorization and point the target system to the relevant interface for sales orders in the target ERP.
- Field mapping: Configure according to the comparison table above. Encoding fields (warehouse, item, customer) uniformly go through the "Encoding Mapping" node, with the mapping table placed in Qeasy's mapping management, so adding new warehouses or items later does not require modifying the flow.
- Red-invoice flag handling: Add a "Constant Assignment" or "Expression" node in the middleware to explicitly set the red-invoice field to the value defined by the target system (for example, 1), and do not rely on the source side.
- Header and body staged writing: Use Qeasy's staged writing capability to write the header first to obtain the target document number, and then write the body; line items use a loop node, with failed lines recorded separately in an exception table so they do not affect other lines.
- Idempotency control: Use "source document number + document date" as the idempotency key, and enable deduplication on the Qeasy side to avoid red-invoice duplicates caused by repeated triggers.
- Exception handling: Configure error routing so that missing field mapping, interface timeouts, and document locks each follow their own alerting and retry paths, rather than being dumped into a single exception pool.
Implementation Steps
- Determine the incremental starting point: Align with the business side on "which after-sales orders after which timestamp should be the incremental starting point"; the source system pull interface usually supports incremental pulling by update time.
- Complete encoding mapping: First connect the three master data types—warehouse, item, and customer—and place them in Qeasy's mapping management. This step is a prerequisite for stable after-sales write-back.
- Trigger a full sync once: During the initial go-live, run a full sync to fill historical after-sales orders into the ERP, confirming that document numbers do not conflict and that the red-invoice direction is correct.
- Switch to incremental and schedule frequency: After the full sync runs without reconciliation issues, switch to scheduled execution. Since after-sales order frequency is usually low, scheduling every 10–15 minutes is sufficient and avoids excessive pull pressure on the source system.
- Reconciliation and monitoring: Run an amount reconciliation once per day (after-sales amount vs. red-invoice sales order amount). The Qeasy console provides visual reports, and abnormal documents automatically fall into a to-do list.
Lessons Learned from the Field
- A typical mistake is to treat the red-invoice flag only as a field mapping and forget to enforce a value in the middleware layer. Different stores and document types on the source side may produce inconsistent red-invoice flags, so the safe approach is to not trust the source side and explicitly assign a constant in the middleware.
- Encoding mapping scattered across multiple flows causes painful later maintenance. In one project, the warehouse mapping existed simultaneously in three tables, and one table was missed during modification, causing some after-sales orders to be written back with empty warehouses. It is recommended to centrally manage encoding mapping; Qeasy's mapping management is designed for exactly this scenario.
- Writing header and body in one shot causes a single failed line to lose the entire document. A typical mistake is to use a one-shot interface carrying the body, where one failed line causes the entire document to be rolled back by the target system. The safe approach is to split header and body into two stages and retry failed lines individually.
- Schedule frequency set too high brings down the source system. After-sales increment is often minute-level, but the source system interface has QPS limits, which is a common pitfall. It is recommended to perform load testing first and then select the frequency based on business latency.
- No idempotency key causes duplicate red-invoice documents during compensation. After-sales orders often need to be re-pushed due to state changes, and without an idempotency key, each compensation creates a new red-invoice sales order, which fails to reconcile with finance.
Applicable and Non-Applicable Scenarios
Applicable: After-sales returns need to generate red-invoice sales orders document by document; master data for customers, items, and warehouses has already been encoded in a unified way; reconciliation granularity requires document-level. Not applicable: After-sales volume is large enough to require batch merging into red-invoice sales orders; the target ERP does not support a red-invoice flag field and can only express through negative quantities; master data for customers and items has not yet been connected, and the early stage where encoding mapping cannot yet be done.