Practical Guide to Synchronizing Online Sales Return Orders to Sales Return Documents

What Problem This Strategy Solves

After an online channel generates a return and the after-sales process is complete, the finance and inventory systems may still lack a sales return document, delaying return receipt and accounting. In an actual project, we used the Qeasy Data Integration Platform to synchronize completed return transactions to the target system. Only valid returns are processed, the store acts as the return customer, and the document is saved and approved automatically so that return operations enter a unified supply-chain workflow.

Data Flow and Field Mapping

The overall chain is: completed online return transactions in the source system are processed by the Qeasy Data Integration Platform, where status filtering, time-based pagination, detail merging, and field conversion are completed. The platform then generates a sales return document in the target system.

The source filters must be fixed to tradeStatus=9090, which indicates that the return is complete; tradeTypeList=8,12, which limits the data to online return types; and isDelete=0, which excludes deleted records. The incremental window spans the last synchronization time to the current time, avoiding a full extraction on every run.

The key master-document mappings are:

The detail structure is based on goodsDetail, and return or batch data is associated through tradeId and subTradeId. The core mappings are: goodsNo → FMaterialId.FNumber, barcode → FCMKBarCode, sendCount/actualSendCount/sellCount → FQty, unit → FUnitID, batchNo → FLOT, sellPrice → FPrice, sellTotal → FAmount, and subTradeId → FThirdSrcEntryId. The actual return quantity is taken from goodsDelivery.sendCount first, with a fallback sequence when it is unavailable. If batch or expiry management is enabled, production and expiration dates are also mapped to their corresponding target fields.

Encoding mappings should be maintained centrally instead of being scattered across workflow scripts. Qeasy centrally manages customer, material, and unit code mappings. When an internal identifier is required, the corresponding identifier can be resolved by customer code.

How to Configure It in Qeasy

First, create the source connection and use the non-sensitive transaction query capability to read data by modification time with pagination. The query must include the completed-return status, online return type, and non-deleted condition, with pagination variables handled by the platform.

Second, configure the target connection. Select the sales return document form and the save operation. To support timely return receipt and accounting, automatic submission and approval after saving can be enabled. Keep base-data field verification disabled so that incomplete mappings do not cause the entire batch to fail.

Third, design the transformation model. Process the master fields first, then the collection details. The platform merges product details with optional batch details and converts each row into the target structure. The return time is used as the document date, the store code is used as the return customer, and the return time plus store name form the master note.

Fourth, establish idempotency control. Use sourceAfterNo as the business document number and idempotency identifier. Qeasy should retain execution results so that a successfully processed document is not created again when the source data is pulled repeatedly.

Fifth, complete integration testing and monitoring. Verify pagination, status filtering, quantity fallback, batch fields, and approval results, and inspect transformation logs and target responses. Qeasy’s unified logs make it possible to trace a source business number to the target document.

Implementation Steps

Incremental starting point. For the initial launch, begin from the earliest time permitted by the source system and initialize historical documents. Daily tasks should read from LAST_SYNC_TIME to CURRENT_TIME. Before saving the new watermark, confirm that the current batch has been fully processed; otherwise failed records may fall outside the synchronization window.

Full-data trigger. When encodings or the document structure changes substantially, use a dual-track model consisting of incremental and full-data runs: temporarily suspend or expand the incremental window, execute a historical full-data run, and then compare successful, failed, and pending records by business number. Full-data processing should be used for repair, not as a replacement for daily incremental synchronization.

Staged scheduling. The source can extract data on a schedule like the one in the source material, followed by target execution. Offsetting the two schedules leaves time for transformation and retry. In production, Qeasy task orchestration can also reduce the gap between the two timers.

Go-live sequence. It is recommended to process the header before the body and validate before writing: first verify master fields, then process a small number of product details. After customer, material, and unit mappings are verified, enable automatic approval. Centralized encoding mapping significantly reduces per-document rework.

Acceptance criteria. Compare the number of completed returns in the source, generated documents in the target, approval status, and the quantities, batches, amounts, and notes. Sample failed automatic records to confirm that the platform returns a clear reason rather than silently skipping them.

Lessons Learned

1. Filtering only by status. A typical mistake is pulling all online transactions. To avoid failure, the integration must also constrain the return type and exclude deleted records.

2. Using a system-generated primary key for idempotency. The source business number is the appropriate business key. Retain the source and target document relationship to prevent duplicate returns during retries.

3. Always using one quantity field. Some detail records do not contain the actual received return quantity, which can result in zero. Use the fallback sequence sendCount → actualSendCount → sellCount.

4. Assuming batch data always exists. Do not populate batch fields for materials without batch management. Only merge batchNo, production date, and expiration date when batch management is enabled. Material, unit, and store encodings must also be mapped in advance.

5. Advancing the watermark regardless of results. If a target operation fails but the successful timestamp is still advanced, the record disappears from future windows. Advance the watermark only after the batch is complete or has entered a traceable queue, and retain retry records.

Suitable and Unsuitable Scenarios

This strategy is suitable for private-deployment supply-chain environments where online after-sales status is clear, the target uses the store as the return customer, and sales return documents need to be generated automatically. Cross-warehouse splitting, complex return-and-exchange combinations, manually completed source data, or businesses that do not use stores as business partners should use separate strategies or be normalized in the intermediate layer before synchronization.