Authoritative Tutorial: Jackyun Return/Exchange Order Query Interface Field Handbook

What This Interface Solves

In the return/exchange flow of retail and distribution businesses, the shipment portion of "return-with-shipment" orders is the key evidence for supply chain reconciliation. This interface incrementally pulls order-type=92 return/exchange shipment details from Jackyun by consign time, writing back logistics name, tracking number, and consign time into the enterprise MySQL reconciliation table. It supports the BDS reconciliation system in completing order verification and logistics status synchronization.

Interface Capability Overview

• API: jackyun.tradenotsensitiveinfos.list.get
• System: Jackyun·Qimen (JkyQM)
• Authentication: Jackyun Open Platform OAuth/AppKey; in Qeasy Cloud this is usually managed by the Qimen Gateway Adapter, which handles credentials and signing.
• Request: POST form/JSON. Common body fields include tradeType, startConsignTime, endConsignTime, modified_begin, modified_end, tradeNo, pageSize, pageIndex.
• Response: JSON. Outer data is the order list; each order object contains the 40+ fields listed in this handbook. goodsDetail and tradeOrderPayList are arrays; tradeOrderColumnExt is a custom object.
• Pagination: pageIndex starts at 0, pageSize defaults to 100. In Qeasy Cloud, the runtime auto-paginates based on hasNext/total until exhausted.
• Incremental Mode: Use startConsignTime/endConsignTime windows by consign time, typically with a 1-day step. When using modification time, modified_begin/end must not exceed 7 days.

Typical Field Mapping

How to Configure on Qeasy Cloud

On the Qeasy Cloud Data Integration Platform, this type of interface is typically delivered as a two-stage strategy: a query adapter plus a downstream EXECUTE write-back strategy.

1. Adapter Selection: Choose the Jackyun·Qimen adapter, configure AppKey/Secret and the Qimen gateway URL; the platform automatically signs requests and handles timestamps.
2. Metadata Modeling: Set tradeId as id and tradeNo as number; bind incremental variables {{LAST_SYNC_TIME}} and {{CURRENT_TIME}} to startConsignTime/endConsignTime.
3. Field Mapper: Qeasy Cloud auto-generates mappings logisticName→send_logistic_name, mainPostid→send_main_post_id, consignTime→consign_time. Complex fields like goodsDetail can be flattened into a child table or stored as JSON in MySQL.
4. Write-back Strategy: The downstream EXECUTE strategy updates supplier_return_change using orderNo/tradeNo as the WHERE clause; Qeasy Cloud dedupes by primary key to avoid duplicate writes.
5. Scheduling & Monitoring: Schedule via crontab (hourly/daily); monitoring shows pagination progress and failed records, enabling breakpoint resumption.

Cross-Scenario Practical Points

• Separate primary key from business key: tradeId for dedup, tradeNo for business number; mixing them breaks idempotency.
• Don't rely solely on modified_begin for increments: For return/exchange scenarios, consign-time windows perform better and avoid irrelevant triggers.
• Use orderNo, not tradeNo, in write-back WHERE: Most customer return/exchange tables join on shipment number; using tradeNo yields zero updates.
• Filter deleted records: isDelete=1 records pollute reconciliation data if written back; add a filter step in the Qeasy Cloud transformer.
• Be tolerant with complex fields: goodsDetail may be null on some orders; provide an empty-array fallback in the mapper to avoid downstream JSON parse errors.
• Isolate credentials: In private deployments, manage AppKey/Secret through the Qeasy Cloud credential vault; never commit them to code repositories.

Pitfall Recap

• Pitfall 1: Wrong tradeType yields no data. In a real project, tradeType was set to 91 (return-only), missing shipment data. Pin tradeType=92 in Qeasy Cloud request parameters and validate with sandbox orders.
• Pitfall 2: Incomplete pagination causes data loss. When pageSize=100 and hasNext=true, submitting without auto-pagination drops the tail page. Qeasy Cloud auto-paginates by default, but custom scripts that build pageIndex manually are risky.
• Pitfall 3: modified_begin/end interval exceeds 7 days. The server rejects it. Slice by day, fetching only 1-day windows per run.
• Pitfall 4: Writing back empty mainPostid. Some partially shipped orders have empty tracking numbers; writing them back makes the reconciliation system think the order is shipped. Add null checks in the transformer.
• Pitfall 5: Timezone drift misaligns incremental windows. consignTime is a local-time string; without converting to UTC before storing in MySQL, the next incremental run re-pulls the same batch.

When to Use

This interface is suitable for writing back shipment information and reconciling "return-with-shipment" (tradeType=92) orders, especially when retail/distribution enterprises need to synchronize Jackyun shipment status to their self-built MySQL reconciliation tables. For pure return (tradeType=91) or pure exchange (tradeType=90) flows, use the corresponding interfaces; for stockout details, use inventory-domain query interfaces instead.