Sync Strategy: Sales Return Orders from Jushuitan to Kingdee Cloud Xingchen
What This Strategy Solves
Sales return orders are the most overlooked part of the supply chain loop. In one retail project, the front end used a retail SaaS for store and e-commerce orders, while the back end used a cloud finance ERP for accounting. Each side booked its own records, and refund amounts, inventory write-offs, and receivable reversals frequently disagreed.
The goal of this strategy is specific: push sales return orders generated in the source system to the finance ERP at the individual document level, so that every document matches one-to-one, refund amounts align, and inventory adjustments point in the correct direction.
Data Flow and Field Mapping
The data flow has two segments: source system → Qeasy data integration platform → target system.
Our design on the customer site is: the source return document first lands in an intermediate table inside Qeasy, where field standardization, null handling, and code mapping are performed, then the data is written into the target system in its return-order API format. This segment is the most easily overlooked step; pushing raw source data directly will guarantee reconciliation failures three months later.
Key field comparison (only fields where we have hit issues in real projects):
| Business Meaning | Source Field | Target Field | Handling Notes |
|---|---|---|---|
| Original document number | io_id / refund_no | srcBillNo | Unique identifier; keep source original value |
| Document date | io_date | bizDate | Mind time zone; source may include HH:mm:ss |
| Customer code | customer_id | customerCode | Use master data mapping table, no hardcoding |
| Warehouse code | warehouse_id | stockCode | Warehouse codes differ across systems; common pitfall |
| Material code | sku_id | materialCode | Material master sync must complete first |
| Return quantity | qty | qty | Units must be unified |
| Refund amount | refund_amount | amount | Tax-inclusive flag must be explicit |
| Line number | line_no | lineNo | Header and body written in stages |
How to Configure on Qeasy
The whole configuration is completed inside the Qeasy data integration platform's strategy editor, with three core nodes:
1. Source Node (Sales Return Order) Select the source-side "Sales Return Order" API. The recommended pull strategy is "incremental by modification time," with an explicit start date. Do not default to the system enablement date, otherwise the first full sync will be very slow.
2. Intermediate Layer (Qeasy) This is the core of the strategy. Centralized code mapping management is a common Qeasy customer practice: keep the source-target mapping for customer, material, and warehouse codes in a single mapping table that is shared across all subsequent sync strategies. Change once, all strategies pick it up.
The intermediate layer also handles type conversion, null-value fallbacks, and tax-exclusive back-calculation of refund amounts.
3. Target Node (Target Sales Return Order - Individual) Use the non-Qimen open-API direct connection. In our practice the Qimen channel frequently fails for individual return scenarios; this is a hard-earned conclusion. When writing, split header and body into stages: write the header first to get the returned document number, then write the body using that document number. This avoids dirty data when the full submission fails.
Implementation Steps
We typically roll out in three phases:
Phase 1: Incremental Start Point Configure a clear first-pull start date inside Qeasy, sync only return orders generated after that date, and run for three business days. The goal is to validate code mapping and field mapping accuracy; a small number of manual entries is acceptable at this stage.
Phase 2: Full Trigger After the incremental logic is stable, trigger one historical full backfill. Once the full run completes, reconcile document by document between the two systems, list the differences, and adjust them manually. This step is mandatory for go-live; do not skip it.
Phase 3: Scheduling Frequency For the production environment, our recommended frequency is: incremental every 15 minutes + a full validation run once per day in the early morning. The dual-track pattern of incremental plus full is a common Qeasy customer approach; it ensures freshness while catching drift in the early morning window.
Pitfall Review
Pitfall 1: Hardcoded Customer Codes The classic mistake is to write the source customer_id directly into the target. The target then rejects the document because the code does not exist. The safe approach is to maintain the mapping in a Qeasy intermediate table.
Pitfall 2: Misaligned Tax Inclusion on Refund Amounts The source is tax-inclusive, the target expects tax-exclusive amounts, and the intermediate layer does not back-calculate. Finance reconciliation breaks immediately.
Pitfall 3: Wrong Channel Choice For the individual sales return order, the non-Qimen open API is more stable. This has been validated across multiple projects; do not choose a channel by intuition.
Pitfall 4: Missing Line Numbers If line numbers are not assigned when pushing the full document, the target system merges multiple lines, and the original correspondence cannot be recovered later during write-off.
Pitfall 5: Incremental Start Time Drift Qeasy's incremental start point is based on the business date, not the system time. If source operators backfill historical documents, those documents are missed. The safe approach is to do a monthly reconciliation and backfill the missing orders.
Suitable and Unsuitable Scenarios
Suitable: Source is the retail SaaS, target is the cloud finance ERP, document-level one-by-one return sync is required, and customer and material codes are already maintained in the Qeasy mapping table; fits retail and distribution scenarios.
Not suitable: Scenarios that require consolidated summary writes, scenarios that need the Qimen channel for batch processing, and scenarios where source-side material master sync has not yet completed.