From WMS Purchase Return Outbound to Kingdee Cloud Purchase Return Material: A Single-Strategy Sync Walkthrough
What This Strategy Solves (Scenario and Value)
In one retail supply chain integration project, the customer's WMS side produces dozens to hundreds of purchase return outbound documents every day. Returns from the warehouse, supplier rejections, and batch quality issues all need to flow back into the ERP as purchase return material documents, so that purchase inbound cost can be reversed, supplier payables refreshed, and inventory book values updated. If the two sides drift out of sync, finance month-end reconciliation breaks down. We use the Qeasy Data Integration Platform to deliver a single strategy that stably pushes the return outbound documents into the ERP-side document creation entry point. The value is to centralize "return facts" in one place in the ERP.
Data Flow and Field Mapping (Source → Middle Layer → Target)
Data starts from the WMS, enters the Qeasy middle layer for cleansing and mapping, and is then written into Kingdee Cloud. On the WMS side, the purchase return outbound query API (with detail) is called, and on the Kingdee side, the batchSave batch execution entry point materializes the data as purchase return material documents.
Below is a key field mapping table. Codes and organization fields are strongly recommended to be centrally managed on Qeasy, instead of being scattered across conversion expressions for each field:
| Business Meaning | WMS Source Field | Middle Layer Handling | Kingdee Target Field | Notes |
|---|---|---|---|---|
| Document Number | return_no | Direct pass-through | FBillNo | Same doc no. used on both sides |
| Return Material Date | check_time (ms) | FROM_UNIXTIME(ts/1000, '%Y-%m-%d %H:%i:%s') | FDate | Timestamp to readable date |
| Stock Org | return_no | _findCollection to look up an existing FBillNo | FStockOrgId | Need a queryable org mapping collection |
| Purchase Org | Same as above | Same lookup | FPurchaseOrgId | Distinguished from stock org |
| Settle Org | Same as above | Same lookup | FSettleOrgId | Aligned with purchase org |
| Settle Type | Not directly given by source | Brought in from PO or supplier master | FSETTLETYPEID | Maintain in code mapping in advance |
How to Configure on Qeasy
In the Qeasy platform, this strategy has a WebAPI (query) source and an EXECUTE (write) target. There are four key configuration points:
First, the source metadata.api is wdt.purchase.purchasereturn.querywithdetail. Enable idCheck and buildModel, use the return document number return_no as the idempotency key, and deduplicate by document number when pulling back returns to avoid duplicate fetches.
Second, the target uses batchSave, and organization-type fields are uniformly resolved by the "code mapping" component — this is a common pattern among Qeasy customers: centralized code mapping. We maintain the stock org, purchase org, settle org, and settle type in one mapping table and only reference them in the strategy, instead of hardcoding them in expressions.
Third, the detail lines (table body) are placed into a separate child-table mapping. Material codes, quantities, batches, and warehouses are landed in phases. Phase one writes the header first, phase two fills in the details — this is the typical header-body phased approach. This avoids dirty documents with "header but no body" on the ERP side.
Fourth, enable autoFillResponse so the platform auto-populates returned fields back into the context. This makes it easier to use return_no to look up organizations and suppliers later, and avoids repeating _findCollection for every field.
Implementation Steps
In a real project, we split this strategy into three phases:
Phase 1: Incremental start point. Use "last successful time + document status" as the incremental start point, and run a backfill for historical unsynced return outbound documents. The incremental start point should not be set as the system go-live day itself, otherwise return data from the previous days will be missed.
Phase 2: Full trigger. After the backfill completes, run a manually triggered full reload to ensure any data missed during the incremental window also enters the target. On Qeasy, simply duplicate the strategy and remove the incremental condition — do not "modify while running" on the original strategy. This is the stable practice.
Phase 3: Scheduling frequency. The source crontab is set at minute 50 of every hour, and the target at minute 59, leaving a 10-minute window for middle-layer persistence and field processing. Cover the business window only (e.g. 7:00–22:00); no need to run at night. This forms an "incremental + full dual-track" rhythm: daily incremental + monthly full validation.
Lessons Learned from the Field
Here are some pitfalls we hit on real customer sites:
- Organization fields hardcoded in expressions everywhere. The typical mistake is writing
_findCollectionfor every field, so when the ERP side reorganizes, dozens of expressions break at once. The stable practice is to centralize organization, settle type, and supplier codes in the "code mapping" component. - Header lands before the body, producing dirty documents in Kingdee. Some teams try to save header and body in one
batchSaveto save effort. When detail lines are large or a row is missing a field, you end up with header-only documents. We adopt header-body phasing: generate the header first, then fill in the body. Failures can be retried and the target side is not polluted. - Timestamp not normalized for timezone or precision. The
check_timefrom the WMS is a millisecond Unix timestamp; writing it directly into the Kingdee date field is rejected. You must useFROM_UNIXTIMEin the middle layer and confirm the precision Kingdee requires (with or without hours/minutes/seconds). - Duplicate fetches produce duplicate documents in Kingdee. If
idCheckis off, or the source API does not support exact deduplication byreturn_no, the same return document will be pushed multiple times. Idempotency check by document number before each push is a basic discipline. - Missing PO linkage for return documents. Kingdee often needs to trace back to the original purchase order to get the org and settle type. We pre-build a "return → purchase order → org/settle type" chain in the code mapping, instead of assembling it on the fly in expressions, to avoid lookup misses at runtime.
When to Use and When Not to Use
Use when: WMS-side return outbound documents map one-to-one to ERP-side purchase return material documents, the document number can be carried across both sides, and organizations/suppliers can be converged through code mapping on Qeasy in a private-deployment supply chain context. Do not use when: the return flow involves multi-level approvals, requires manual intervention for amount reversals, or the organization/supplier structures on the two sides differ so much that code mapping cannot reconcile them.