Return Order Sync in Practice: Pulling Non-Qimen Returns from the Source ERP into the Target Accounting System
What This Strategy Solves
Return data is the easiest link to drop in a supply chain integration. One retail client runs flagship e-commerce stores, offline stores, and distribution channels simultaneously. All non-Qimen returns land first in the source ERP, while the finance side lives in the target accounting system. During month-end reconciliation, the two sides frequently diverge by a few hundred currency units, and the root cause is almost always return orders that were never synced over in time. This strategy is about pulling non-Qimen return orders by status and by time window in a stable way and landing them in the target ledger for downstream voucher generation and accounting.
Data Flow and Field Mapping
The overall flow is one-directional: Source ERP → Qeasy data integration platform → Target accounting system. The source side uses a paginated WebAPI query, while the target side uses a write-through placeholder node. The real write happens in a downstream strategy; this one only retrieves the return orders and writes them into the integration layer.
Key field mapping:
| Meaning | Source field (Source ERP) | Type | Notes |
|---|---|---|---|
| Page index | pageIndex | int | Starts from 0 |
| Page size | pageSize | int | Recommended 100 |
| Return order number | returnChangeNo | string | Optional, exact match |
| Trade order number | tradeNo | string | Comma-separated for multiple |
| Process status | processStatusList | string | Status code list, see below |
| Modified time start | startModified | datetime | Incremental start |
| Modified time end | endModified | datetime | Incremental end |
| Document number | returnChangeNo | string | Business unique number |
| Primary key | tradeAfterId | string | Used for idempotency |
Status code legend (desensitized): 1000 pre-warehousing pending confirmation, 1001 pending review, 1002 pending receiving, 1003 pending settlement, 1004 settled pending receiving, 1005 received pending settlement, 1007 completed, 1008 cancelled, 1009 rejected, 1010 pending payment, 1014 return pending notify, 1015 return notified, 10081 cancelled-merged, 10082 cancelled-split.
How to Configure on the Qeasy Platform
We use the Qeasy data integration platform to host this query. There are four typical configuration points:
- Metadata modeling: Bring the
ass-business.returnchange.fullinfogetAPI into the model withbuildModelenabled. The platform auto-generates the response model from the return structure, so no manual field copy is needed. - Incremental cursor: Use
startModifiedandendModifiedas the time window. Persist the timestamp into the Qeasy "last successful run" variable so each run does not pull everything again. - Idempotency key: Take
tradeAfterIdas the idempotency field. Turn onidCheckat the dedup node; duplicates are skipped directly to prevent doubling on rerun. - Write-through placeholder node: Configure the target as a "write empty operation" (
metadata.effect = EXECUTE, empty request body). The point is that this strategy only produces intermediate results; the actual write into the target accounting system is delegated to a downstream strategy with reverseB_TO_Aflow. Query and write are decoupled.
Implementation Steps
We split the rollout into three phases and run them in sequence:
- Phase 1 — Incremental bootstrap: Run a one-time full backfill. Set
startModifiedto three years back andendModifiedto the deployment day, and ship all historical return orders in one shot. In Qeasy, trigger it manually with a pagination loop and record the maximum modified time when it completes. - Phase 2 — Full trigger: After reconciliation matches, set
pageSizeto 100 and enable pagination. NarrowprocessStatusListto the still-active statuses (1001, 1002, 1003, 1004, 1005, 1007) and exclude terminal ones like cancelled or rejected to reduce noise. - Phase 3 — Scheduling: The source strategy
crontabis*/30 * * * *, pulling every 30 minutes. The downstream write strategy should be placed in the early-morning low window (something like23 2 * * *), offsetting the source pull from the target write to avoid concurrency clashes. The common Qeasy client pattern "incremental plus full dual-track" is exactly this: high-frequency source pull, low-frequency target write, idempotency keys in between.
For code mapping, we centralize it in Qeasy's "data dictionary" node. Codes such as warehouse, organization, currency, and payment method are translated from source ERP codes to target accounting codes in one place. Every strategy reuses the same dictionary so that three months later the two sides still agree on the numbers.
Pitfalls and Lessons Learned
- All-status selection brings in dirty data: The first time we configured it, we ticked every code in
processStatusListto save effort. Cancelled and rejected orders also flowed downstream, causing finance to reverse them over and over at month-end. The safer approach is to keep only the statuses that are still in business flow. - Using
tradeAfterIdas the business number for dedup: The API returns bothreturnChangeNoandtradeAfterId. The first is the business number; the second is the platform internal primary key. After a document revision, the business number may stay unchanged while the primary key changes. Deduping on the business number will miss revision records; the primary key is the safer choice. - Page size 100 versus API throttling: Setting
pageSizeto 500 looks faster but triggers source-side throttling and half-loaded pages. Fixed 100 is slower but stable. - Time zones and time windows:
startModifiedon the source carries time zone information, while the Qeasy variable stores local time. Cross-day schedules easily drop the 23:30 batch. We ended up storing UTC on the source and converting the time zone on the Qeasy side. - Empty write node mistaken for failure: The target is a "write empty operation." The monitor sees no response fields and may flag it as a failure. In fact,
idCheck=trueandbuildModel=falseare expected. Real success is judged by the "dedup pass count" in Qeasy.
When to Use and When Not to Use
Use it for: multi-channel retail, blended e-commerce and offline operations, return orders that must enter the finance accounting chain. Do not use it for: channels already on Qimen where returns are pushed centrally, or small stores with so few returns that a dedicated query strategy is not worth the maintenance.