Sales Return Order Cross-System Sync: An End-to-End Guide from Jushuitan to Kingdee Cloud Xingchen
What this strategy solves
In retail and distribution scenarios, return orders are usually born in the e-commerce ERP first and must be pushed to the finance ERP as red-letter sales documents for bookkeeping, stock rollback, and receivable adjustment. In one of our recent projects, a supply-chain retail customer had warehouse returns accepted in Jushuitan, but no corresponding red-letter documents in Xingchen — leading to over 300 mismatched items during monthly reconciliation.
The strategy here is to build a one-way, low-latency, traceable sync link from Jushuitan sales return orders to Xingchen sales return orders. The hard part is not transport, but unified coding and document status.
Data flow and field mapping
The flow is three-stage: source (Jushuitan) → Qeasy middleware → target (Kingdee Cloud Xingchen). The middleware handles cleaning, transformation, default value filling, and flagging.
| Business meaning | Source (Jushuitan) | Middleware (Qeasy) | Target (Xingchen) |
|---|---|---|---|
| Document number | io_id (return out ID) | return_bill_no | FBillNo |
| Document type | type=return out | fixed RETURN_OUT | FBillTypeID=Sales Return |
| Customer code | shop_id / customer | customer master key mapping | FCustID |
| Material code | sku_id | material master key mapping (depends on master data) | FMaterialID |
| Warehouse | warehouse_id | warehouse code mapping | FStockID |
| Quantity | qty | unit conversion | FQty |
| Price / amount | price / amount | tax-included/excluded conversion | FPrice / FAmount |
| Refund amount | refund | independent field, for voucher | remarks + custom field |
| Document status | io_status | normalized to pending/approved | FDocumentStatus |
The tricky fields are customer and material codes — both systems have completely different primary keys. You must rely on upstream master-data strategies (material sync, customer sync) before this strategy can run, otherwise you get 404s immediately.
How to configure in Qeasy
We use the Qeasy integration platform on the customer site to host this strategy. There are three typical configuration blocks:
- Source extraction: Use Jushuitan's open API endpoints such as
/openapi/jushuitan/returnout. The Qeasy source adapter handles pagination, rate limiting, and checkpoint resume. - Transformation layer: In the Qeasy data transformation node, maintain a centralized coding mapping table (customer, material, warehouse) — never hardcode in individual strategies. A common Qeasy customer pattern is to host mappings in a separate "master data library" strategy, which this strategy only reads.
- Target write: On the Xingchen side, use either the custom API or standard open interface. The Qeasy target adapter assembles header and body per Xingchen's JSON contract, with two-phase header/body submission: write header first to get the internal ID, then write body arrays carrying that ID.
We also recommend a dual-track pattern: full + incremental. The full sync covers initial backfill; the incremental sync handles daily rolling. They use different entry points but share the same mapping and transformation logic.
Implementation steps
We usually split the rollout into four steps, each with a clear deliverable.
- Step 1: Upstream first. Make sure the "material info → Qeasy" and "Qeasy → Xingchen material" strategies are stable, and the middleware mapping table has at least 7 days of stable samples.
- Step 2: Incremental reconciliation. Take the last N days of Jushuitan returns as the incremental starting point (usually
io_modified_time > last_success_time), only push "pending approval" documents, run for 3 days. - Step 3: Full trigger. In the early-morning low-peak window (2:00–5:00), run one historical full backfill for
io_ids never pushed, then stop — to avoid clashing with incremental. - Step 4: Scheduling frequency. Daily scheduling of every 5–10 minutes is sufficient; return orders are low-frequency. Add retry and alerting; failed records go to a dead-letter queue for manual handling.
Lessons learned
- Classic mistake: running before master data is ready. Without customer and material keys in Xingchen, all return documents fail. The safe approach is to set this strategy's
depends_onto material and customer strategies, and auto-skip when upstream isn't stable. - Refund amount vs sales amount confusion. Jushuitan's
refundis the actual refund paid to the consumer; Xingchen needs the red-letter sales document amount. These often differ — handlerefundindependently, do not reuse the original sales order's amount field. - Status machine mismatch. Jushuitan's
io_statushas many stages; Xingchen only accepts a few. The middleware must compress and map statuses, otherwise you'll see "received in source, still pending in target". - No idempotency key. The same
io_idmay be pushed twice under network jitter. Always useFBillNoas the idempotency key on the Qeasy target side; Xingchen should de-duplicate by document number. - Historical full sync hammering the live database. Backfill ran without rate limiting and hit Xingchen's API throttle. Safe approach: concurrency = 2, batch size ≤ 200 during full sync window, then release incremental.
When to use and when not to
Use when: E-commerce returns need a red-letter document in the finance system within T+1; SKU scale is tens of thousands and daily return volume is under a few hundred.
Don't use when: Two-way sync with conflict merging is needed (this strategy is one-way); cross-entity or cross-book returns (use a transfer document in Xingchen, not a sync); sub-minute real-time full inventory rollback is required.