After-sales Order Sync from Jushuitan to ERP Sales Return: Offline Store Scenario
What This Strategy Solves
Offline-store after-sales returns need to be posted into the ERP as sales return documents, but Jushuitan's after-sales flow uses a non-Qimen private channel. Its fields, status machine, and identifiers do not naturally match the ERP's sales return form. The pain points concentrate on three things: the meanings of refund amount, original bill number, SKU code, and store code differ on the two sides, which easily causes wrong, missing, or duplicate bills; meanwhile, offline stores have no scheduled polling window of their own, so the middle layer must reliably and periodically pull after-sales orders.
Data Flow and Field Mapping
The source is Jushuitan's non-Qimen after-sales order interface, the target is the ERP sales return document (offline store), and the middle layer is the Qeasy integration platform, which handles retrieval, mapping, transformation, and push-out.
Key field mapping (typical, adjust as needed):
| Business meaning | Jushuitan after-sales (source) | Qeasy middle layer | ERP sales return (target) |
|---|---|---|---|
| Original bill no. | so_id / refund_no | Normalized to src_bill_no | src_bill_no |
| Store code | shop_id | Converted via code mapping | store_code |
| SKU code | sku_id | Routed through SKU→material mapping | material_code |
| Refund amount | refund_amount | Normalized by currency/tax | refund_amt |
| Return quantity | qty | Quantity = actual returned qty | return_qty |
| Business date | modified | Converted to yyyy-MM-dd | bus_date |
| Status | status | Status machine: pending/paid/closed | bill_status |
Code mapping is the most critical step. A common pattern on customer sites: put store codes, SKU codes, warehouse codes, and reason codes into a single mapping table on Qeasy, then share it across every document strategy (sales order, outbound, return), so that mappings are not duplicated.
How to Configure on Qeasy
- Register source and target systems: source is Jushuitan (private deployment), with non-Qimen credentials provided by the customer; target is the ERP sales return API.
- Build the data source: select the after-sales module, enable "incremental by modified time", and pick a fixed historical start point to avoid missing bills.
- Configure middle-layer mapping: use Qeasy's mapping node to project source fields onto the target structure per the table above; drive code mapping through a "lookup table" node rather than hardcoding it in a script, so a single change propagates across the chain.
- Split header and body: sales returns have a header + body structure. Use Qeasy's "staged" mode—write the header first, then push body rows carrying src_bill_no, so a body-row failure does not roll back the whole document.
- Retry and alerting: configure different retry counts and alert channels for three typical failure types: network jitter, field-length overflow, and unmapped codes.
Implementation Steps
Phased scheduling is the most useful arrangement in this implementation:
- Full backfill phase: before going live, run a one-shot full backfill to bring N months of historical after-sales orders into the ERP; run the full job off-peak and verify amount parity with a reconciliation script afterwards.
- Incremental start point: after the full backfill finishes, switch to incremental mode starting from "the modified time of the last successfully pushed record".
- Schedule frequency: for offline-store returns, a 5–10 minute interval is sufficient; higher frequency tends to collide with source-side rate limits.
- Dependencies and ordering: the prerequisite for this strategy is that the product master data sync is already stable—the SKU mapping table must be populated, otherwise the target will reject return documents for missing materials.
- Reconciliation loop: run a light reconciliation every night to confirm that source-side refunded bills are status=paid in the ERP, and push any difference list to the ops channel.
Pitfalls Revisited
- "Product master data not synced first" is the #1 crash site. Going live with return sync without it causes ~90% of failures to concentrate on unmapped SKU codes. The safe approach is to confirm the material sync strategy has been running stably for at least one week before turning this on.
- The non-Qimen after-sales status machine is more complex than expected. Before "paid" there are intermediate states such as "pending review" and "partial refund"; writing the final state directly into the ERP will drop bills. The middle layer must maintain a state transition table and only push the ERP final state when the status actually transitions from "processing" to "paid".
- The same after-sales bill gets called back multiple times. The source triggers a
modifiedchange on refund completion, closing, and remark updates, so incremental retrieval easily produces duplicate pushes. Use src_bill_no + business date as the idempotency key and make the target do upsert instead of insert. - Amount and currency drift. The source refund amount may be tax-inclusive, while the ERP expects tax-exclusive. The middle layer must split by tax code rather than passing the raw value through.
- The offline-store "store code" is numeric on the source but a prefixed string on the target. The most common pitfall here is silent truncation during type conversion, which makes every return document in the ERP belong to the same store.
When to Use and When Not to Use
Use when: offline-store after-sales returns flow through Jushuitan's non-Qimen channel and the target ERP sales return is a header+body structure. Do not use when: cross-border multi-currency refund scenarios, or standard retail stores using the Qimen channel (use the standard Qimen after-sales template instead, no need for a dedicated strategy).