Syncing Kingdee Return Material Requests to Wangdiantong Purchase Return Orders: A Single-Strategy Tutorial

What This Strategy Solves

A return-material order is the document a company uses to send excess or non-conforming materials back from a usage site to a supplier or warehouse. For one retail enterprise we worked with, the daily pain point was clear: once a return-material request was approved in Kingdee Cloud, a corresponding purchase return order still had to be created manually in Wangdiantong to drive warehouse receiving and accounting reversal. Manual re-entry is slow and error-prone. We built this into a schedulable, traceable sync strategy on the Qeasy integration platform.

Data Flow and Field Mapping

The direction is: Kingdee Cloud (source) → Qeasy middleware → Wangdiantong Qijie Qimen (target).

On the source side we call Kingdee's executeBillQuery, filtered by document status FDocumentStatus = C (approved). On the target side we call Wangdiantong's wdt.purchase.purchasereturn.createorder.

Key field mapping:

Business meaning	Kingdee source field	Wangdiantong target field	Handling notes
Document number	FBillNo	orderInfo.order_no	Idempotency key to avoid duplicates
Document type	FBillTypeID.Fnumber	orderInfo.order_type	Centralized mapping recommended
Document date	FDate	orderInfo.order_time	Format per target requirements
Return reason	FReturnReason	orderInfo.remark	Truncate long text, handle newlines
Entry line id	FEntity_FEntryID	detailList[].detail_no	Header/line processed in stages
Material code	FMaterialID.Fnumber	detailList[].sku_code	Depends on material master sync first
Return quantity	FQty	detailList[].qty	Convert units if needed
Warehouse	FStockID.Fnumber	detailList[].warehouse_no	Warehouse mapping is a common pitfall

Configuring on Qeasy

In the Qeasy strategy canvas, configure as follows:

Source component: Select Kingdee Cloud, API executeBillQuery, with filter FDocumentStatus = 'C' AND FBillTypeID.Fnumber IN (...).
Target component: Select Wangdiantong Qimen, API wdt.purchase.purchasereturn.createorder; set is_check based on whether auto-approval is desired.
Code mapping: Maintain material code, warehouse code, and document-type mappings centrally in Qeasy's Mapping Center so other strategies can reuse them.
Idempotency: Use FBillNo as the dedup key and write it into Qeasy's built-in synced-record table.
Header/line staging: Process the header first to get the Wangdiantong document id, then write it back into src_order_id on each line for traceability and reconciliation.

Implementation Steps

Incremental starting point: On first go-live, record the maximum approval timestamp T0 in Kingdee as the initial incremental anchor; thereafter roll forward by FDate >= T0.
Full trigger: Pick a low-traffic window (e.g. nighttime) to run a one-time full backfill for any historical un-synced requests. Switch to incremental after that.
Schedule frequency: Source */30 7-20 * * *, target */31 7-20 * * *, offset by 1 minute to avoid concurrent writes. A common pattern among Qeasy customers is the "dual-track" approach: incremental polling during the day, full verification at night.
Monitoring and alerts: Configure retry (3 attempts with exponential backoff) and IM alerts (Feishu/DingTalk) inside Qeasy's runtime monitor.
Reconciliation: Run a weekly diff reconciliation comparing document numbers and quantities on both sides, exporting an Excel report.

Pitfalls We Have Seen

Missing document-type mapping: Kingdee's TLSQDD01 SYS (standard return) and TLSQDD0D04 SYS (cash-purchase return) collapse into a single type on the Wangdiantong side if not mapped, breaking downstream reports.
Inconsistent warehouse codes: Kingdee uses finance-oriented warehouse codes; Wangdiantong uses logistics-oriented ones. Passing the value straight through triggers "warehouse not found." Do the conversion in Qeasy's Mapping Center.
Truncated detail lines: When a document has more than 200 lines, some interfaces silently truncate. Add batching logic on the source side or confirm the target API supports paginated submission.
Duplicate pushes: Too-short intervals or manual reruns send the same FBillNo repeatedly. Always enable idempotency keys and write to Qeasy's synced-record table.
Status semantics differ: Kingdee's "approved" is C, but some custom workflows still use B (in review). Filtering must strictly follow the business definition, or unfinished documents will be pushed through.

When to Use and When Not to

Use it for retail/distribution enterprises that integrate Kingdee with Wangdiantong and need the finance system to drive return flows in the WMS. Do not use it for pure manufacturing scenarios (outsourced return-material needs different document types), nor for bi-directional reversal flows (split into two separate strategies with a state machine instead).