Purchase Returns Sync from Jushuitan to Kingdee Cloud Galaxy: A Single-Strategy Deep Dive
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:
| Field | Meaning | Value in Strategy |
|---|---|---|
| page_index | Page number | Starts at 1 |
| page_size | Page size | 50 (API cap) |
| modified_begin | Modification start time | `{{LAST_SYNC_TIME |
| modified_end | Modification end time | `{{CURRENT_TIME |
| status | Document status | Confirmed (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 Field | Meaning | Source / Handling |
|---|---|---|
| FBillNo | Document number | {{io_id}} direct from source |
| FDate | Return date | {{io_date}} |
| FStockOrgId | Return-from org | Fixed code |
| FSupplierID | Supplier | _findCollection find supplier_code from supplier mapping where supplier_id={{seller_id}} |
| FBiller / entity | Return line items | Expanded 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:
- Source strategy: select the source connector, choose
POST /open/purchaseout/query, hard-codestatustoConfirmed, and bindmodified_begin/modified_endto the platform variablesLAST_SYNC_TIMEandCURRENT_TIME. Use the built-in paginator to loop pages until empty. - 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.
- Target strategy: pick
batchSaveon the target connector, assemble the request body per the table above, and enableidCheck=trueso already-written documents are not regenerated. - Scheduling: the source strategy uses
crontab=every 10 minutes during 1–2 AM(*/10 1-2 * * *); the target usescrontab=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_TIMEto 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
- Time window exceeding 7 days — the API errors out. The source enforces a 7-day maximum between
modified_beginandmodified_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. statusnot 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-codestatus=Confirmedon the source filter.page_sizeset 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".- 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.
FBillNoalone is not enough as an idempotency key. In edge cases the source renumbers documents; you must verify bothio_idand 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.