Purchase Return Sync in Practice: Kingdee Cloud to Wangdiantong Integration

What This Strategy Solves

Synchronizing purchase return orders from an ERP to a WMS sounds like a simple outbound flow: after approval, the document is pushed, the target system auto-checks it, and inventory is decremented. But in the field we often see a different picture—return quantities with wrong sign, warehouse codes hiding in line items, suppliers or SKUs missing in the target system. Three months later the numbers drift, and finance plus warehouse spend nights reconciling.

The core problem this strategy solves in one sentence: cleanly, traceably, and incrementally push Kingdee Cloud approved purchase returns into Wangdiantong, so they auto-check and decrement inventory. In one retail supply chain project we delivered this through Qeasy Data Integration, turning the return loop from "manual Excel exports" into "natural system flow."

Data Flow and Field Mapping

The pipeline is straightforward: Kingdee Cloud V2 (source) → Qeasy Data Integration platform (middleware) → Wangdiantong QM (target). The source side uses a QUERY API to pull documents; the target side uses an EXECUTE API to push them. The middleware handles field mapping, status filtering, and master data encoding translation.

The header-level mapping boils down to three things: supplier supplierid_number → provider_no, document bill_no → outer_no, line array material_entity → detail_list. Note that warehouse_no is not read from the header but from the line-level material_entity_stock_number—a peculiarity of Kingdee Cloud's data model.

Lines are processed in a loop: warehouse code, spec code, goods name, unit, quantity, tax-inclusive and tax-exclusive prices, batch number, production date, expiry date—each mapped one by one. Important: the source quantity qty is typically negative (signaling outbound). Before synchronization, confirm whether the target side requires a sign flip.

How to Configure on Qeasy

On Qeasy Data Integration, this strategy only needs one integration plan with a source QUERY, a target EXECUTE, and the mappings in between.

Source configuration: API /jdy/v2/scm/pur_ret, type QUERY, method GET; pagination page=1, page_size=10; time window start_bill_date={{LAST_SYNC_TIME|datetime}}, end_bill_date={{CURRENT_TIME|datetime}}; detail lookup /jdy/v2/scm/pur_ret_detail—the platform auto-fetches lines by document id.

Target configuration: API wdt.purchase.return.push, type WebAPI EXECUTE, method POST; primary key outer_no bound to source bill_no; line node detail_list directly bound to source material_entity, looped by the platform.

Mapping layer configuration: this is where engineering experience shows. We usually recommend the "centralized encoding mapping" pattern to customers—keep supplier, warehouse, and SKU encoding mappings in independent master data plans, and let the return plan only reference them. When a new supplier or warehouse appears, you only add one row in the master data side, and the return pipeline reuses it automatically. The is_check field is a constant "1" on the target.

Implementation Steps

We recommend a "full baseline + incremental takeover" dual-track rollout for return document sync.

Step 1: full sync trigger. On go-live day, run a full sync to push all historically approved return orders at once. The goal is to establish the outer_no ↔ Wangdiantong document mapping so the incremental phase won't create duplicates. After it completes, switch scheduling to incremental mode.

Step 2: incremental starting point. Set last_sync_time to "full sync completion time minus 1 hour" to avoid missing boundary documents. This step matters—at one manufacturer go-live, the team forgot to rewind, and three documents stuck on the boundary were missed. The warehouse only noticed the day after when stock did not balance.

Step 3: scheduling frequency. For business hours, use */10 8-22 * * *—every 10 minutes from 8am to 10pm. Return orders are not high-frequency; 10 minutes is enough. If a customer wants faster inventory decrement, drop it to 5 minutes—there's no need to go lower. Turning off the schedule outside business hours reduces source-side API pressure.

Step 4: go-live observation window. Within the first three days after launch, monitor three things: document count alignment, correct inventory decrement direction, and no exceptions on target-side auto-check. A common gotcha—Wangdiantong uses outer_no for deduplication; repeated pushes update the original document, so never drop the outer_no check in incremental logic.

Pitfalls Recap

1. Wrong location for warehouse code. The most common issue. Kingdee stores the warehouse on line items, not on the header; pulling from the header yields null or wrong values. The safe approach is to confirm source data structure first, then decide which layer to read.

2. Master data not synced first. If suppliers, SKUs, or warehouses do not exist in Wangdiantong, the return push will fail with "code not found." We saw one project where master data went live a week late, causing the entire return pipeline to fail for that week. The safe approach: run master data sync first, then document sync.

3. Quantity sign flipped. Kingdee return quantities are negative. If you do not validate during mapping, inventory can "increase" instead of decrease. Add a sign-handling step in the mapping layer, or at least verify with real documents during testing.

4. Batch management mismatch. If batch management is enabled but batch_no, production_date, or expire_date is missing on either side, batch-level inventory decrement will be wrong. Confirm both sides have consistent batch settings before go-live.

5. Incomplete line field mapping. Lines carry four price/tax fields: tax_price, tax_amount, price, amount. Dropping one of them can cause the target to reject the document, or amounts drift. Print the line mapping table and tick off each field one by one.

When to Use and When Not

Use when: the supplier return flow uses Kingdee as the approval hub and Wangdiantong as the inventory execution hub—typical for retail or distribution enterprises; document volume is moderate; reconciliation latency under 30 minutes is required.

Don't use when: Kingdee and Wangdiantong are deployed with an official built-in connector; or the return flow requires reversing a goods receipt before generating a return—that usually needs goods receipt to land first, then triggers a return.