WangdianTong Purchase Order Query API Field Guide: queryWithDetail Authoritative Tutorial

What This API Solves

In retail and distribution scenarios, the purchase order is the most common collaborative document between ERP and e-commerce warehouse systems. The purchase.PurchaseOrder.queryWithDetail API in WangdianTong Flagship Edition is designed to pull header records together with all detail lines in a single call. Its typical use is synchronizing purchase orders to Kingdee Cloud Cosmic as purchase orders or receiving notices, or driving the purchase inbound and settlement workflow.

API Capability Overview

• Authentication: WangdianTong Flagship Edition uses application-level AppKey/Secret signing, with the token carried in the request header. The WangdianTong connector on the Qeasy data integration platform has encapsulated the authentication flow.
• Request Structure: purchase.PurchaseOrder.queryWithDetail accepts two parts: params (business conditions such as time range, status, warehouse, and supplier) and pager (pagination parameters, typically with page_size between 100 and 200).
• Response Structure: The header and detail rows are returned in a flattened form. Each row corresponds to one purchase detail line, and header fields are repeated on every row. When aggregating, you must deduplicate by purchase_id to recover the header, then associate details through detail_list_purchase_id.
• Pagination / Incremental Mode: Pagination is supported. Incremental pulls usually rely on start_time / end_time (modification time) combined with the modified field. On the Qeasy platform, the default schedule runs every 7 minutes.

Typical Field Mappings

How to Configure on Qeasy

On the Qeasy data integration platform, this API typically appears as a "query source":

1. Create a data query strategy, select the WangdianTong Flagship Edition adapter, and choose purchase.PurchaseOrder.queryWithDetail;
2. In the Qeasy field mapper, map purchase_no to both the number and id fields as the anchor for deduplication and cross-system matching;
3. Use ${LAST_MODIFIED_TIME} as the params variable for the incremental window, and set pager.page_size to 100~200;
4. Configure the Target as "Write Empty Operation" to indicate this is a pure query strategy whose data is staged in the intermediate database for other sync strategies to consume;
5. Use the */7 * * * * schedule; the Qeasy runtime automatically handles pagination merging and retry on failure.

Cross-Scenario Practical Points

1. Flattened structure must be reconstructed: When aggregating, take the first row per purchase_id as the header, then pull details by detail_list_purchase_id; otherwise the downstream Kingdee write will fail.
2. Use modified, not created, for the incremental cursor: Audit, reverse-audit, and edit operations all change modified; using created will miss documents.
3. Status dictionaries must be pre-maintained: WangdianTong status values (Pending Audit, Approved, Partially Arrived, Fully Arrived, etc.) do not have a one-to-one mapping with Kingdee document states. Build the conversion table in the Qeasy field mapper ahead of time.
4. All amount fields are strings: Every fee-type field is of type string. Convert to decimal first before aggregation or arithmetic, otherwise concatenation errors will occur.
5. Unit conversion is error-prone: detail_list_num is the base-unit quantity, num2 is the auxiliary-unit quantity, and unit_ratio is the conversion factor. Confirm which unit the target document expects before synchronizing to Kingdee.
6. detail_list_new_price is a calculated field: Do not store it as source data directly. The safe approach is to recalculate on demand so that changes in the source calculation convention do not break data consistency.

Pitfall Review

• Pitfall 1: Treating flattened data as one-to-one header-detail when writing. The result was that the Kingdee side generated N purchase orders for a single WangdianTong document.
• Pitfall 2: Using created as the incremental start, causing missed documents. A retail customer found in the first week after go-live that historically approved but still-changing purchase orders were all missed; switching to modified fixed it.
• Pitfall 3: Confusion between tax-inclusive and tax-exclusive interpretations of tax_price and tax_amount. Different ledgers in the source system are configured inconsistently. Always land a snapshot field in the intermediate database and unify the convention before pushing downstream.
• Pitfall 4: Unannounced status value changes. After a source system upgrade, the status dictionary added "Partially Arrived", but Kingdee kept receiving the old status, causing the receiving notice to be generated at the wrong moment.
• Pitfall 5: Duplicate purchase_no. In very rare cases the source system has multiple documents under the same business number. Always use purchase_id as the primary key and purchase_no as the business key as a double safeguard.

When to Use This

Applicable when WangdianTong acts as the purchase order source and you need to synchronize the full order and its details to a downstream ERP such as Kingdee Cloud Cosmic to drive purchase orders, receiving notices, purchase inbound, and settlement workflows. Boundary: this is a read-only API and does not write back; to push Kingdee's audit / settlement status back into WangdianTong, you need a separate write strategy.