Qeasy Cloud
Get Started

Return Notice Sync in Practice: Connecting After-Sales Orders from a Retail Platform to a Mid-Market ERP

· 吕修远· Integration Solutions· 6 views· 4 min read
JushuitanKingdee Cloud退货同步售后单据轻易云供应链集成

What This Strategy Solves

For a retail enterprise, after-sales returns need to flow automatically from the e-commerce side into the ERP as a return notice, which then drives red-letter outbound delivery and accounts-receivable reversal. The retail platform records consumer-initiated refund and return requests, while the mid-market ERP needs a document that can go through approval and inventory reversal. We used the Qeasy integration platform to handle this with a single strategy, pushing after-sales documents incrementally into the ERP so that after-sales, warehousing, and finance stay aligned over the long term.

Data Flow and Field Mapping

The data flow is one-way: the retail platform (after-sales order) → the Qeasy middleware layer → the mid-market ERP (return notice). The middleware layer is responsible for value interception, cleansing, code conversion, and idempotency.

The key field mapping below covers the fields that most often cause trouble in real projects:

Source Field (After-Sales Order)Qeasy MiddlewareTarget Field (Return Notice)Notes
io_id (document number)strategy_biz_noFBillNoDocument number, used as idempotency key
modifiedorder_modified_atFModifyDateField used for the incremental start point
shop_idorg_idFOrgIdStore or organization mapping
pay_amountrefund_totalFRefundAmountRefund total, sign must be normalized
items[].sku_idsku_codeFMaterialIdProduct code mapped to the ERP material internal key
items[].qtyqty_absFQtyReturn quantity takes the absolute value
so_idsrc_bill_noFSourceBillNoOriginal sales order number linkage

Centralized mapping tables are one of the patterns we commonly see at Qeasy customers: materials, stores, warehouses, and customers are all maintained in a single mapping table in the middleware. Incoming codes from the source are first looked up in this table before being written to the target, so that later changes to the code system do not scatter across multiple strategies.

How to Configure It on Qeasy

Step 1: Create the source connection in the Qeasy integration platform, connect to the after-sales order API of the retail platform, and pull incremental data.

Step 2: Create the target connection, authorize access to the mid-market ERP, and prepare the standard API for the return notice. Note that on the ERP side the document header and lines are separated; staged header-and-lines is another common pattern we see at customer sites: first write the header and obtain FBillNo, then submit the line items in batch. If anything in between fails, it does not affect other documents.

Step 3: Orchestrate the flow in the strategy canvas: trigger → pull source data → cleanse and map → write target header → write target lines → write back status. The key point is to use io_id as the idempotency key. On the target side, FBillNo serves as the unique constraint, and on the Qeasy side, the strategy run record provides deduplication. Three layers of idempotency ensure no duplicate documents.

Step 4: Field mapping configuration: code-type fields go through the central mapping table; amount-type fields pass through an absolute-value and sign-normalization step in the middleware; date-type fields are uniformly formatted to the yyyy-MM-dd HH:mm:ss format required by the ERP.

Implementation Steps

Phase 1: Incremental start point. Start by using the modified field for timestamp-based increment, with the starting time set to seven days before the project go-live date, to fill in after-sales orders that were not yet closed.

Phase 2: Full trigger. For the first run, use full load to confirm that documents on both sides can be fully aligned, then switch to incremental. During the full-load phase, it is recommended to run at end of day to avoid concurrent pressure on the source.

Phase 3: Scheduling frequency. After go-live, run incremental every 15 minutes, which is close to real time while still allowing multiple requests to be merged into a batch during peak after-sales hours. If there is still a backlog within the 15-minute window, Qeasy's automatic retry provides a fallback.

Phase 4: Exception handling. Three typical exceptions — source-side timeout, target-side validation failure, and missing codes — are routed to different queues for manual or automatic rerun.

The dual-track full-and-incremental approach is another common pattern at Qeasy customers: full load for go-live reconciliation, incremental for long-term running, and the two are not mixed in the same schedule.

Post-Mortem Tips

First, sign normalization for refund amounts. In the source after-sales order, pay_amount is negative by default; pushing it as is will cause the ERP to treat it as a red-letter payable. This is a common pitfall; the safe approach is to add a sign-normalization step in the middleware so that refund amounts are uniformly converted to positive.

Second, take the absolute value for return quantities. Likewise, the quantity field in the after-sales order is negative, while the ERP's return notice requires a positive value.

Third, staged header-and-lines submission. A typical mistake is to submit the header and lines all at once; if any line fails, the entire document is voided and the source may also roll back. Splitting the header and lines into two nodes in Qeasy, with the header going first and the lines batched afterward, significantly improves stability.

Fourth, missing codes. If the product code on the source side has not been registered on the ERP side, submission will be rejected by the target. We recommend adding a pre-validation in the strategy: when an unmapped sku_id is encountered, route it to a manual-handling queue rather than letting the entire document fail.

Fifth, idempotency-key design. The safe approach is to use a composite idempotency key of io_id plus shop_id; using io_id alone may cause collisions in multi-store scenarios.

Suitable and Unsuitable Scenarios

Suitable for retail or distribution enterprises with large after-sales volumes that need automatic generation of return notices to drive subsequent red-letter outbound delivery and financial reversal. Not suitable for scenarios where after-sales processes require manual intervention, where multiple legal entities settle separately, or where returns and refunds are not closed-loopped in the same system. In those cases, it is recommended to first stabilize master-data governance before introducing integration.

Original content. Please credit the source when reposting: https://www.qeasy.cloud/insights/solutions/strat-jushuitan-kingdee-cloud-8231-ok-1650c5ee

Comments