Practical Tutorial: Syncing Kingdee Material Return Requests to Wangdiantong Purchase Return Orders

What This Strategy Solves

In one real engagement, an enterprise IT team ran into a typical pain point: material return requests approved in Kingdee Cloud Stellar needed to land as purchase return orders in Wangdiantong·Qiemen, otherwise supplier reconciliation and inventory write-offs would lag. It looks like a simple two-document copy, but mismatched document status, line items, warehouse codes, and supplier codes will cause the two sides to drift apart within three months. On the customer site, we used the Qeasy Data Integration Platform to host this strategy, pushing Kingdee material return requests steadily into Wangdiantong and closing the loop.

Data Flow and Field Mapping

Data flow: Kingdee Cloud Stellar (source) → Qeasy middle layer → Wangdiantong·Qiemen (target).

The source calls executeBillQuery to fetch approved material return requests; the target calls wdt.purchase.return.push to write purchase return orders. Key field mapping:

How to Configure on Qeasy

In the Qeasy console, this strategy has four configuration blocks:

First, the source connector binds to Kingdee Cloud Stellar's API gateway and selects executeBillQuery. Enable the filter FDocumentStatus = 'C' so that dirty data (draft, created, in-review) is not pulled.

Second, field mapping is done through the visual mapping panel. Code-type fields (warehouse, supplier, material) all go through Qeasy's central "code mapping" module rather than being scattered across strategies. This is a common pattern we see among Qeasy customers: once a new warehouse is added or a supplier changes, one edit propagates to all strategies.

Third, the target write API selects wdt.purchase.return.push, mapping source entry fields to the detail_list array node. Header and body are processed in stages on Qeasy—generate the header to get the target document number, then push line items in batch, and finally write back the association.

Fourth, the scheduling policy sets the source cron to */5 * * * * and the target to */10 * * * *. The source runs slightly more frequently than the target so that the downstream always has data to consume without losing documents due to upstream bursts.

Implementation Steps

Before going live, we typically split into three stages:

Stage 1: Incremental starting point. On the Kingdee side, pick a clear timestamp (e.g., T-1 23:59:59) as the incremental starting point, ensuring approved documents flow into the middle layer in time order. The key is to verify Kingdee's audit fields (modified time / approve time) are accurate.

Stage 2: Full backfill trigger. On the cutover day, manually trigger a full historical backfill so that legacy material return requests are completed in Wangdiantong. After the full run completes, switch to incremental. Running full and incremental in tandem is another common robust pattern among Qeasy customers.

Stage 3: Schedule frequency and monitoring. Source runs every 5 minutes, target every 10 minutes. Use Qeasy's runtime dashboard to watch backlog, failure rate, and average latency. For the first two weeks, manually sample failed documents daily; from the second month onward, drop to weekly sampling.

Pitfall Review

Pitfall 1: Document status not filtered. Forgetting to filter FDocumentStatus = 'C' on the source side pushes drafts or in-review documents downstream, resulting in a pile of voided return orders in Wangdiantong. This is easy to stumble on. The safe approach is to hard-filter status in the source query.

Pitfall 2: Warehouse code is not unique 1:1. Multiple warehouses under one Kingdee organization share similar codes. Without distinguishing by organization dimension, inbound and return warehouses get mixed up. The typical mistake is treating the code as globally unique, when it must be the combination of organization + code.

Pitfall 3: Line items lost. Pushing a whole JSON blob makes the target ignore the detail rows. The safe approach is to explicitly declare detail_list as an array node in Qeasy, and map each field like FEntity_FEntryID, product, quantity, batch one by one.

Pitfall 4: Idempotency key missing. Without passing outer_no or with the source document number changing, reruns create duplicate return orders. Use FBillNo as the idempotency key and enable idempotency check in Qeasy.

Pitfall 5: Purchase order reference switch. Wangdiantong has a configuration "purchase return order must reference purchase order." When the switch is off, leaving purchase_no empty is fine; when the switch is on but the field is empty, the entire document fails. Confirm the switch state with the business before going live.

When It Fits and When It Doesn't

Fits: scenarios where the source has a clear state machine (post-approval flow), the target supports idempotency, and master data has been synced ahead of return orders. Doesn't fit: scenarios with frequent unapprove/modify on the source, no idempotency guarantee on the target, or cross-organization return write-offs requiring secondary approval.