Kingdee Purchase Return Material Request to Jushuitan Purchase Return: A Single-Strategy Sync Tutorial

What This Strategy Solves

In a real retail supply-chain integration project, we ran into a high-frequency pain point: the purchase return process was split across two systems. When the warehouse raised a return-material request in Kingdee Cloud, that document had to be pushed to Jushuitan so a corresponding purchase return could be generated—only then could the supplier settle the return and reverse stock in Jushuitan. Doing it manually via Excel export-and-import was error-prone and slow; inventory books drifted within three days.

The essence of this single strategy is to take the Kingdee return-material request as the single source of truth and automatically transform it into a Jushuitan purchase return. It belongs to the return-closed-loop in supply chain and must run alongside base strategies such as material sync and purchase order sync; it cannot stand alone.

Data Flow and Field Mapping

The flow is straightforward: Kingdee Cloud (source) → Qeasy integration platform middleware → Jushuitan (target). The source pulls incremental documents via a query API, and the target writes new return documents via a write API.

Key field mapping:

How to Configure It on Qeasy

In the Qeasy data integration platform, this strategy is configured as a pair of integration flows: the source uses Kingdee's executeBillQuery, and the target uses Jushuitan's jushuitan.purchaseout.upload WebAPI.

Key configuration points:

1. Source API: Use Kingdee's executeBillQuery with FDocumentStatus = 'A' (approved) as a filter, so drafts are not pushed.
2. Target API: jushuitan.purchaseout.upload, write the external id directly as {{FBillNo}} for idempotency.
3. Centralised encoding mapping: Supplier codes and warehouse codes are maintained in Qeasy's mapping table module rather than hard-coded in scripts—one of the most common patterns among Qeasy customers.
4. Idempotency and deduplication: The target API has idCheck = true, combined with the uniqueness of external_id, reruns will not create duplicate documents.
5. Auto-fill response: Enable autoFillResponse so the internal document number returned by the target shows up directly in Qeasy logs, which simplifies troubleshooting.
6. Header and body in phases: The header is written first, then body lines are written row by row. This is the safe approach for documents like returns that have detail lines, avoiding half-written documents in the database.

Implementation Steps

We split the rollout into three phases:

1. Incremental starting point: At the first go-live, pick a historical anchor (e.g., the system cutover date) as the starting point. Backfill a batch of historical approved return-material requests in ascending document-number order—this is a one-off full sync, not part of the daily schedule.
2. Full trigger: Once backfill is complete, switch to incremental. Incremental pulls use FModifyDate > last successful timestamp on the source; Qeasy records the watermark internally, so nothing is missed or duplicated.
3. Schedule frequency: The source runs every 10 minutes (avoiding the hour mark), and the target runs 3 minutes later to stagger. The source cron is 2-59/10 6-23 * * *, and the target is 5-59/10 6-23 * * *. This staggering reduces instantaneous pressure on the target.

After go-live, we recommend observing for three full working days—checking that document numbers correspond one-to-one and that the inventory write-back amounts are correct—before opening it up to business users.

Pitfalls and Lessons Learned

1. Supplier codes don't match, and the entire document is rejected. Kingdee supplier masters and Jushuitan supplier masters are not the same encoding. A typical mistake is to dump Kingdee's supplier code straight into the target. The safe approach is to maintain a supplier mapping table in Qeasy and use _mongoQuery to look up Jushuitan's supplier_id by Kingdee code before writing.
2. Warehouse code missing, target falls back to default warehouse. If wms_co_id is empty, Jushuitan places the stock in a virtual warehouse by default, which corrupts the inventory ledger. We map Kingdee's FStockId to Jushuitan warehouse codes in Qeasy's mapping table and validate before batch runs.
3. Draft status pushed by mistake. If the source filter doesn't restrict FDocumentStatus, drafts get synced too and pollute the data. Make "approved" a hard prerequisite.
4. Return reason and amount fields ignored. In retail scenarios, customers often analyse returns by reason. We pass through a remark field on the header and map the amount, quantity, and return reason on each body line—rather than just pushing the document number.
5. Duplicate documents on the target side. If the watermark in Qeasy breaks, a re-pull may push already-synced documents again. The external_id idempotency field plus idCheck provides a safety net, but the more robust approach is to add a pre-deduplication check in Qeasy.

Applicable and Non-applicable Scenarios

Applicable: Retail or distribution companies where Kingdee Cloud serves as the financial/supply-chain back office and Jushuitan handles e-commerce warehousing, and where the return process must be closed-loop across both systems; high return-document volume with tight reconciliation SLAs.

Not applicable: The Kingdee-side return process is not digitalised and still relies on paper; or Jushuitan-side returns are created manually by the warehouse in the WMS and do not need upstream driving. In the latter case, forcing an integration only adds maintenance overhead.

Applicable and Non-applicable Scenarios (Supplementary)

One more boundary note: this strategy belongs to the "return documents" subdomain and depends on base sync strategies (materials, purchase orders, supplier masters) being ready first. If the customer's materials have not yet been created in Jushuitan, even if the return document is pushed successfully, no valid SKU can be generated, leading to the awkward situation of "document succeeds, stock fails." Therefore, the rollout order must be A first, B second—you cannot fan them out in parallel.