Qeasy Cloud
Get Started

Purchase Returns Sync from Jushuitan to Kingdee Cloud Galaxy: A Single-Strategy Deep Dive

· Integration Solutions· 8 views· 4 min read
JushuitanKingdee Cloud供应链集成退货同步轻易云增量调度

What This Strategy Solves

Returns sync sounds like a simple document copy: a return happens upstream, push the data downstream. But anyone who has run this on-site knows that document status, modification time window, supplier/material code mapping, and return-from organization — get any one of these wrong and the books won't reconcile. This article dissects one purchase-returns sync strategy end to end: pulling confirmed return orders from the source system, then writing them as material-return bills in the target system.

We deliver this on the Qeasy data-integration platform at customer sites. The typical pattern is to centralize status filtering, the incremental cursor, and field mapping inside the strategy itself, so future tweaks happen in one place.

Data Flow and Field Mapping

The overall flow is: source system (return-order API) → Qeasy middle layer (filter, transform, lookup) → target system (batchSave to material-return bill).

Source Side: Pulling Confirmed Returns

The source exposes POST /open/purchaseout/query, a WebAPI. Key request fields:

FieldMeaningValue in Strategy
page_indexPage numberStarts at 1
page_sizePage size50 (API cap)
modified_beginModification start time`{{LAST_SYNC_TIME
modified_endModification end time`{{CURRENT_TIME
statusDocument statusConfirmed (only effective docs)

The source uses io_id as the unique document number, which also serves as the idempotency key downstream.

Target Side: Writing the Material-Return Bill

The target calls batchSave, with the document type fixed as a material-return bill. Key field mappings:

Target FieldMeaningSource / Handling
FBillNoDocument number{{io_id}} direct from source
FDateReturn date{{io_date}}
FStockOrgIdReturn-from orgFixed code
FSupplierIDSupplier_findCollection find supplier_code from supplier mapping where supplier_id={{seller_id}}
FBiller / entityReturn line itemsExpanded row-by-row from source detail array

Note: the gap between modified_begin and modified_end cannot exceed 7 days — a hard constraint on the source side, revisited in the pitfalls section.

Configuring on Qeasy

On the Qeasy data-integration platform, this strategy is split into a paired source strategy and target strategy:

  1. Source strategy: select the source connector, choose POST /open/purchaseout/query, hard-code status to Confirmed, and bind modified_begin/modified_end to the platform variables LAST_SYNC_TIME and CURRENT_TIME. Use the built-in paginator to loop pages until empty.
  2. Middle transformation: in the Qeasy field-mapping canvas, drag source fields to target fields. Supplier code must go through a lookup table — never hard-code it. This is one of the most common patterns we see among Qeasy customers: centralized code mapping. Put supplier, material, and organization codes in a single mapping table so that when either side renames a code, only one place changes.
  3. Target strategy: pick batchSave on the target connector, assemble the request body per the table above, and enable idCheck=true so already-written documents are not regenerated.
  4. Scheduling: the source strategy uses crontab=every 10 minutes during 1–2 AM (*/10 1-2 * * *); the target uses crontab=every 10 minutes during 8 AM–10 PM (3-59/10 8-22 * * *). They are intentionally staggered so the target does not start writing before the source finishes pulling.

Implementation Steps

We typically roll this out for customers in three phases:

  • Phase 1: Set the incremental starting point. Run a one-time full backfill to confirm the pipeline works; then switch to incremental mode and manually set LAST_SYNC_TIME to midnight of the cutover day. After that, the cursor rolls every 10 minutes.
  • Phase 2: Phased scheduling. First, run a read-only week (target strategy in dry-run: write generated request bodies to logs and review manually). Once verified, enable writes.
  • Phase 3: Steady-state operation. The source strategy pulls during off-peak early morning; the target writes during daytime business hours; off-peak hours catch up leftovers. Incremental plus full dual-track is another common pattern among Qeasy customers: incremental runs daily, with a weekly/monthly full reconciliation as a safety net.

Pitfalls We Have Hit

  1. Time window exceeding 7 days — the API errors out. The source enforces a 7-day maximum between modified_begin and modified_end. If the middleware or scheduler stalls and accumulates a backlog, Qeasy must implement resume-from-breakpoint: roll the cursor forward only, never try to backfill a long window in one shot.
  2. status not hard-coded pulls back draft documents. If left unset, the source returns multiple statuses and the target rejects them, leaving you baffled during triage. The safe move is to hard-code status=Confirmed on the source filter.
  3. page_size set above 50 silently truncates. The source caps at 50; setting 100 does not error but only returns the first 50, leading you to think "no more data".
  4. Supplier code hard-coded into the strategy. Once the two sides diverge in coding schemes, documents land under the wrong supplier and reconciliation becomes painful. Centralized code mapping is essentially mandatory.
  5. FBillNo alone is not enough as an idempotency key. In edge cases the source renumbers documents; you must verify both io_id and modification time to prevent duplicate writes.

When to Use and When Not to

Use when: in retail or manufacturing, the upstream ERP/ecommerce mid-platform is the entry point for return entry and the downstream finance/supply-chain system is the ledger and inventory-adjustment point, and you need time-windowed incremental sync of confirmed returns.

Do not use when: real-time (second-level) return-event propagation is required, or the return process spans multi-level approvals across systems and needs line-by-line bidirectional reconciliation. Those scenarios usually call for event-driven + state-machine architectures rather than a single scheduled sync strategy.

Original content. Please credit the source when reposting: https://www.qeasy.cloud/insights/solutions/strat-jushuitan-kingdee-cloud-9390-v1-0-fa9952c9

Comments