Qeasy Cloud
Get Started

Sales Return Order Cross-System Sync: An End-to-End Guide from Jushuitan to Kingdee Cloud Xingchen

· 陈洁琳· Integration Solutions· 20 views· 4 min read
Jushuitan金蝶云星辰销售退货同步轻易云供应链集成跨系统集成

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 meaningSource (Jushuitan)Middleware (Qeasy)Target (Xingchen)
Document numberio_id (return out ID)return_bill_noFBillNo
Document typetype=return outfixed RETURN_OUTFBillTypeID=Sales Return
Customer codeshop_id / customercustomer master key mappingFCustID
Material codesku_idmaterial master key mapping (depends on master data)FMaterialID
Warehousewarehouse_idwarehouse code mappingFStockID
Quantityqtyunit conversionFQty
Price / amountprice / amounttax-included/excluded conversionFPrice / FAmount
Refund amountrefundindependent field, for voucherremarks + custom field
Document statusio_statusnormalized to pending/approvedFDocumentStatus

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:

  1. Source extraction: Use Jushuitan's open API endpoints such as /openapi/jushuitan/returnout. The Qeasy source adapter handles pagination, rate limiting, and checkpoint resume.
  2. 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.
  3. 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

  1. 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_on to material and customer strategies, and auto-skip when upstream isn't stable.
  2. Refund amount vs sales amount confusion. Jushuitan's refund is the actual refund paid to the consumer; Xingchen needs the red-letter sales document amount. These often differ — handle refund independently, do not reuse the original sales order's amount field.
  3. Status machine mismatch. Jushuitan's io_status has 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".
  4. No idempotency key. The same io_id may be pushed twice under network jitter. Always use FBillNo as the idempotency key on the Qeasy target side; Xingchen should de-duplicate by document number.
  5. 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.

Original content. Please credit the source when reposting: https://www.qeasy.cloud/insights/solutions/strat-jushuitan-kingdee-cloud-9521-n46d151a9-5c9a5ac2

Comments