Sync Purchase Returns from Jushuitan to Kingdee Cloud: A Single-Strategy Playbook

What This Strategy Solves

For a retail company, returns originate in Jushuitan while finance and inventory accounting live in Kingdee Cloud. The moment a return happens, three ledgers—warehouse, payables, and stock—must reflect it simultaneously; otherwise you get the awkward situation where e-commerce says 100 units were returned, ERP has no document, and inventory still shows a positive count. This strategy pulls purchase-return documents from Jushuitan incrementally by modification time, filters down to confirmed status only, and writes them into Kingdee Cloud using the return-material document model. It is not a warehouse-style full mirror; it is event-driven, near-real-time sync.

Data Flow and Field Mapping

The pipeline is unidirectional: Source → Qeasy Middle Layer → Target.

On the source side (Jushuitan), the strategy calls the purchase-return query endpoint via HTTP POST, with page size fixed at 50. The time window is controlled by modified_begin and modified_end, and the API enforces a hard constraint: the interval cannot exceed seven days. Status is filtered to Confirmed only; every other status is dropped before reaching the downstream system.

The middle layer does three things: deduplication by document number, field shaping, and translation of Jushuitan seller IDs into Kingdee Cloud supplier master keys. The lookup is written as _findCollection find supplier_code from ... where supplier_id={{seller_id}}, so the mapping table lives in Qeasy and can be maintained centrally.

On the target side (Kingdee Cloud), the strategy invokes batchSave. Document type is fixed to TLD01_SYS and organization code is 100. Key field mappings are:

How to Configure It in Qeasy

In the Qeasy Data Integration Platform, this strategy is a source-strategy + target-strategy pair.

Source-side essentials: API = /open/purchaseout/query, method POST, idempotency field io_id with idCheck enabled, meaning already-written documents do not re-trigger the downstream. Time window variables use {{LAST_SYNC_TIME|datetime}} and {{CURRENT_TIME|datetime}}; Qeasy rolls them forward automatically on each scheduled run.

Target-side essentials: API = batchSave, also enable idCheck. Hard-code constants like document type and return organization so business changes don't drift them between runs. Lookup-style fields such as supplier are best maintained in a Qeasy mapping collection—this is one of the most common patterns among Qeasy customers: centralized code mapping, one place to update, effective everywhere.

If the return document has header + line structure, we recommend the staged header/line approach: write the header first, then push lines row-by-row after success. This avoids whole-document rollback when a single line fails.

Implementation Steps

Step one, run a one-off full trigger to backfill all historical confirmed returns into Kingdee Cloud. Schedule it manually during off-peak hours; no need for a recurring cron.

Step two, once full backfill is verified, switch the strategy to incremental mode. On the source side we recommend */10 1-2 * * * style windows—every 10 minutes during a focused window—to concentrate pull pressure in the early morning. On the target side, run during business hours, e.g. 3-59/10 8-22 * * *, offset from source peaks.

Step three, observe for three days. Watch three signals: duplicate documents, empty suppliers, stock quantity divergence vs. Jushuitan. If any signal trips, stop the strategy before debugging the mapping.

Step four, attach monitoring alerts: two consecutive empty runs, failure rate above threshold, or time-window drift should all page the on-call.

Pitfalls and Lessons Learned

• Time window exceeding seven days returns an error. Jushuitan's API hard-caps the modified_begin / modified_end interval at 7 days. Our first attempt used a 30-day window and immediately got HTTP 400. The safe approach is to bound the window length with Qeasy variables, never breaching the 7-day edge.
• Forgetting to filter on status writes drafts into ERP. If status isn't locked to Confirmed, Jushuitan drafts get pushed to Kingdee Cloud and finance cannot reconcile. The typical mistake is "sync everything first, filter later"—half of the first batch ends up being junk drafts.
• Supplier not mapped causes save failure. Jushuitan seller_id and Kingdee Cloud FSupplierID are different code sets; writing without a mapping yields "base data not found."
• Idempotency key not enabled causes duplicates on retry. If idCheck is off and the scheduler retries—or someone manually reruns—duplicate return documents get created and stock is deducted multiple times.
• Submitting header and lines together rolls back the whole document on a single line error. Staged writes are far safer.

When to Use and When Not to Use

Use when: e-commerce purchase returns need near-real-time entry into ERP for payables and stock accounting; source and target use different code systems but a mapping is feasible; the source API supports time-window incremental queries. Do not use when: returns need to flow through complex approval workflows before posting (switch to status-change triggers); the source API does not support time-window incremental queries (you would be forced into full polling with heavy reconciliation load); or cross-organization splits are required.