Qeasy Cloud
Get Started

Return Order Sync in Practice: Pulling Non-Qimen Returns from the Source ERP into the Target Accounting System

· 何金辉· Integration Solutions· 5 views· 4 min read

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:

MeaningSource field (Source ERP)TypeNotes
Page indexpageIndexintStarts from 0
Page sizepageSizeintRecommended 100
Return order numberreturnChangeNostringOptional, exact match
Trade order numbertradeNostringComma-separated for multiple
Process statusprocessStatusListstringStatus code list, see below
Modified time startstartModifieddatetimeIncremental start
Modified time endendModifieddatetimeIncremental end
Document numberreturnChangeNostringBusiness unique number
Primary keytradeAfterIdstringUsed 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:

  1. Metadata modeling: Bring the ass-business.returnchange.fullinfoget API into the model with buildModel enabled. The platform auto-generates the response model from the return structure, so no manual field copy is needed.
  2. Incremental cursor: Use startModified and endModified as the time window. Persist the timestamp into the Qeasy "last successful run" variable so each run does not pull everything again.
  3. Idempotency key: Take tradeAfterId as the idempotency field. Turn on idCheck at the dedup node; duplicates are skipped directly to prevent doubling on rerun.
  4. 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 reverse B_TO_A flow. 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 startModified to three years back and endModified to 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 pageSize to 100 and enable pagination. Narrow processStatusList to 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 crontab is */30 * * * *, pulling every 30 minutes. The downstream write strategy should be placed in the early-morning low window (something like 23 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

  1. All-status selection brings in dirty data: The first time we configured it, we ticked every code in processStatusList to 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.
  2. Using tradeAfterId as the business number for dedup: The API returns both returnChangeNo and tradeAfterId. 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.
  3. Page size 100 versus API throttling: Setting pageSize to 500 looks faster but triggers source-side throttling and half-loaded pages. Fixed 100 is slower but stable.
  4. Time zones and time windows: startModified on 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.
  5. 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=true and buildModel=false are 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.

Original content. Please credit the source when reposting: https://www.qeasy.cloud/insights/solutions/strat-p2ea595-p4a143d-3954-n15755064-0a1f615c

Comments