Sync Jushuitan Purchase Returns to Kingdee Cloud Cosmic: A Practical Guide to Writing Back Purchase Order Numbers

What This Strategy Solves

In the supply chain of a retail company, Jushuitan handles front-end purchase return entry, while Kingdee Cloud Cosmic serves as the back-end financial and supply chain accounting system. The two sides need a closed loop. In practice, Jushuitan return documents only carry the original e-commerce order number, whereas Kingdee generates a formal return-material document with its own purchase order number. If the Kingdee-side purchase order number is not written back to Jushuitan, financial reconciliation, purchase traceability, and batch verification all break. This strategy pushes Jushuitan return documents to Kingdee and brings back the corresponding purchase order number after Kingdee generates the formal document.

Data Flow and Field Mapping

The overall flow is Jushuitan → Qeasy middle layer → Kingdee Cloud Cosmic, and the write-back phase reverses: Kingdee generates the return-material document → Qeasy → Jushuitan.

Key field mapping (typical items, source first, target second):

• Document number: Jushuitan return number ↔ Kingdee return-material number (generated) ↔ written back to Jushuitan custom field
• Purchase order number: Jushuitan associated purchase order → Kingdee return-material linked purchase receipt → written back as the formal purchase order number
• Item code: Jushuitan SKU ↔ Kingdee material code (mapping maintained centrally on Qeasy)
• Quantity, tax-inclusive unit price, tax amount: Kingdee return-material body strictly follows these fields
• Warehouse: Kingdee warehouse archive (mapped by Jushuitan warehouse code on Qeasy)
• Header remarks: Jushuitan return reason → Kingdee return-material header remarks

Easily missed: the document body. Every detail line of the return-material must be mapped one by one, otherwise the Kingdee receipt amount will not reconcile with the front end.

How to Configure on Qeasy

We use the Qeasy Data Integration Platform on-site to handle the job. A typical configuration has four parts:

1. Source connection: choose the Jushuitan adapter, configure the application key, store authorization scope, and return document query window.

2. Target connection: choose the Kingdee Cloud Cosmic adapter, configure the organization code, login credentials, and return-material document interface permission.

3. Field mapping and scripts: this is a high-risk area. Code mapping is centrally managed in Qeasy's "Code Mapping" module. The mapping tables for items, suppliers, and warehouses are maintained independently, so that when an upstream material strategy (Jushuitan item ← Kingdee material) changes, a single refresh takes effect. Header and body are handled in two phases: map the header first and confirm header save, then add the body lines. This avoids getting the entire document blocked by a detail-field error at the start.

4. Write-back strategy: Qeasy supports using a "Write Back" action to update the Kingdee-returned purchase order number into a custom field on the Jushuitan return document. This step must be triggered only after the Kingdee return-material document is saved successfully. The recommended approach is to use Qeasy's callback/polling mechanism, rather than hard-waiting for the Kingdee response packet inside a single sync.

Implementation Steps

We run this in three phases:

Step 1: define the incremental start point. Use the Jushuitan return document's "modification time" as the incremental cursor. Before first go-live, perform a one-time full backfill of historical unsynced documents; then switch to a 5-minute incremental schedule. The safe pattern is a "dual track of incremental and full": the incremental strategy runs at high frequency for timeliness, and a daily full-validation task backs it up.

Step 2: configure scheduling frequency. Returns are relatively low-frequency. Run every 5–10 minutes during the day, and reduce to every 15 minutes at night, to avoid large-volume syncs during Kingdee month-end closing windows. Qeasy scheduled tasks can be configured separately for working days and non-working days.

Step 3: close the write-back verification loop. In the early days after go-live, manually reconcile every return-material document for the first three days: verify that the Jushuitan return number, Kingdee return-material number, and purchase order number can all be cross-queried from either side. This is the hard acceptance standard for closing the loop.

Lessons Learned

1. Scattered code mapping is the most common pitfall. Item, supplier, and warehouse mappings scattered across multiple strategies lead to inconsistent numbers three months later. We eventually centralized everything in Qeasy's unified mapping tables.

2. Missing body lines. Jushuitan return documents may have multiple entries for the same item, while Kingdee return-material bodies require strict detail lines. The mapping script must persist entries 1:1 by entry sequence without any aggregation.

3. Wrong write-back timing. Waiting for the Kingdee response packet blocks the entire pipeline whenever Kingdee is slow. The safe approach is to persist after Kingdee save, and let Qeasy asynchronously poll and retrieve the purchase order number before writing it back to Jushuitan.

4. Wrong incremental field. Using "creation time" for increments causes missed documents across time zones or manual back-entry. Using "modification time" plus a status filter (audited) is stable.

5. Month-end windows not avoided. During Kingdee month-end or closing periods, the return-material interface is often locked and scheduled tasks fail at scale. The schedule calendar must block these windows, and failed documents should go to a retry queue.

Applicable and Non-Applicable Scenarios

Applicable: e-commerce purchase returns go through Jushuitan on the front end, financial accounting runs on Kingdee Cloud Cosmic, and both sides need a closed-loop reconciliation with bidirectional traceability of the purchase order number. Not applicable: pure internal ERP-to-ERP returns without the need to write back a purchase order number, or environments where Jushuitan and Kingdee organizations have not performed basic data synchronization (items, suppliers). Without the upstream mapping, the downstream strategy will not run.