Authoritative Tutorial on the Wangdiantong Purchase Return Order Query Interface (wdt.purchase.return.query)

What Problem This Interface Solves

In Wangdiantong–Kingdee Cosmos supply chain integration, the purchase return order is the key voucher connecting "purchase inbound" and "supplier return". The wdt.purchase.return.query interface is used to periodically pull return orders and their line items from Wangdiantong and land them as Kingdee purchase return orders or red-letter purchase inbound orders, enabling return status tracking, supplier/warehouse-dimensional return analysis, and traceability back to the purchase order.

Interface Capability Overview

• Authentication: Wangdiantong·QiMen open platform uses AppKey + signature, with requests submitted as application/x-www-form-urlencoded through the QiMen gateway.
• Request structure: Core inputs are start_time, end_time (format yyyy-MM-dd HH:mm:ss) and optional status filtering, supporting incremental pulls by modification time.
• Response structure: Returns return_list (header array) and detail_list (nested line array), linked via return_id.
• Pagination/incremental mode: Typical projects run on a */2 * * * * schedule with time-window incremental sync. We recommend using modified as the watermark and persisting the max consumed timestamp to avoid missed or duplicate records.
• State machine: The status field traverses 9 values: 10/20/30/40/42/44/46/50/60. Only 40 (approved), 50 (partially outbound), and 60 (completed) are truly reconcilable; the rest should be filtered out upstream.

Typical Field Mapping

How to Configure in QeasyCloud

In the QeasyCloud data integration platform, this interface is encapsulated as a standard adapter. The common approach is:

1. Adapter selection: Pick "Wangdiantong·QiMen" as the source system, choose wdt.purchase.return.query as the API. QeasyCloud has pre-built signature, request assembly, and response parsing.
2. Field mapper: The header and detail_list are automatically expanded into two logical tables; the field mapper supports drag-and-drop binding. Kingdee's "Purchase Return Order" or "Red-letter Purchase Inbound Order" can be mapped in one click, with QeasyCloud auto-handling idempotency by return_id + rec_id.
3. Incremental strategy: QeasyCloud supports modified-based incremental out of the box; we recommend a 5–10 minute window to avoid boundary duplicates.
4. Exception routing: Documents in status ∈ {42,44} (push failures) are routed to an exception queue, where engineers can configure dedicated retry channels.
5. Visual logs: Every call's request, response, and latency are recorded; missed or duplicate records can be replayed for troubleshooting.

Cross-Scenario Practical Points

1. Only sync "post-approval" documents: Return orders with status < 40 can be modified or canceled anytime in Wangdiantong; landing them into Kingdee and rolling back later is extremely costly.
2. Always carry unit_ratio on line items: Multi-unit SKUs are the most common source of "doubled/halved quantity" anomalies across systems. A safe practice is to enforce non-null validation in the mapper.
3. Write back via return_no as outer no.: After Kingdee approval, push the Kingdee document number back to Wangdiantong's outer_no to form a bidirectional closed loop that makes reconciliation trivial.
4. Confirm amount semantics before writing: Wangdiantong's amount may be either pre-tax or post-tax; align with finance on tax-included/excluded semantics before go-live to avoid red-letter corrections later.
5. Use modified (not created) as the watermark: Orders under editing or rejection-resubmit don't change created; relying on created alone will inevitably miss data.
6. Prefer supplier/warehouse codes over names: Cross-system reconciliation uses codes; names are only for display and exception investigation.

Pitfall Retrospective

• Pitfall 1: status 42/44 stuck in Kingdee after push. status=42 pending push, 44 push failed are intermediate states in Wangdiantong; syncing them directly leaves Kingdee documents stuck in "pending approval". Fix: Hard-filter out 42/44 and only take 40/50/60.
• Pitfall 2: num is a string, sum overflows. Without CAST, merged line quantities may surface in scientific notation. Fix: Enable type conversion in QeasyCloud's field mapper and standardize to decimal.
• Pitfall 3: Return address province/city/district concatenation exceeds length. Kingdee address fields have length limits and get truncated. Fix: Truncate by length before writing, or split into custom fields.
• Pitfall 4: Incremental window too small, missed records. At a 1-minute window, Wangdiantong's modified sometimes drifts a few seconds from server time. Fix: Widen the window to 5 minutes and advance the watermark as max(modified) - 30s for safety.
• Pitfall 5: Multi-unit SKU quantities don't match. Dropping unit_ratio causes base and auxiliary units to be treated as one. Fix: Mark unit_ratio as mandatory in mapping; error out when missing.

When to Use This Interface

When you need to sync Wangdiantong's purchase return data into ERP (especially Kingdee Cosmos) for supplier reconciliation, red-letter inbound, and return analytics, this interface is the first choice. For lightweight queries or status-only retrieval, you can use Wangdiantong's lightweight API, but for a complete supply chain closed loop, you still need wdt.purchase.return.query to pull both header and line items.