Jky Return-Exchange-Replenishment Order Pagination Query API Field Manual: An Authoritative Tutorial from Flattened Structure to Incremental Sync

What This Interface Solves

In retail and e-commerce supply chain integration, the high-frequency backflow of after-sales documents (returns, exchanges, replenishments) is the core data source for inventory reconciliation, statement settlement, and financial accounting. The Jky "Pagination Query for Return-Exchange-Replenishment Orders" interface serves as the primary data export for this responsibility—it outputs the main table and detail arrays of after-sales orders from the source system in one go, and after being "flattened", it feeds downstream ERP systems such as Kingdee Cloud Skylink for supply chain document landing. The existence of this interface directly bridges the data gap between e-commerce after-sales and ERP financial inventory.

Interface Capability Overview

Jky uses the standard AppKey + signature token authentication mode, with the request body submitted in JSON format. Typical input parameters include pageNo, pageSize, startModified, endModified, tradeAfterStatus, etc. The response body is a paginated structure, with core fields wrapped in a data list. Each record contains a nested array returnChangeGoodsDetail, which needs to be flattened into multiple rows. Incremental synchronization uses the gmtModified field as the time window basis. Pagination cursors are mainly page-number-based increments, with pageSize generally controlled between 50-200 records to balance throughput and timeout risks.

Typical Field Mapping

How to Configure on Qeasy

In the Qeasy data integration platform, this interface is usually encapsulated in a three-stage pattern: "Jky Adapter → Flattening Converter → Field Mapper". The adapter handles signature assembly and paginated fetching, with the platform automatically managing pageNo increments and gmtModified time windows. The flattening converter expands nested arrays into flat rows, with field suffixes (_goodsNo, _returnCount, etc.) automatically derived by the platform. The field mapper then drags and maps the flattened fields to target documents such as Kingdee Cloud Skylink's after-sales inbound orders and receipt orders, and supports expressions for unit conversion, code value translation, and null value fallback. Across multiple customer projects, we have found that this three-stage configuration can compress the development cycle of after-sales order synchronization strategies from one week to half a day.

Cross-Solution Practical Key Points

1. Flattening is mandatory, not optional. In real scenarios, after-sales orders are almost always one-master-multiple-detail structures. Direct landing will cause downstream Kingdee Skylink to only receive the master table, with all details lost, and inventory write-back will inevitably be chaotic.
2. Status machine code values must be fully maintained. Jky after-sales order status has more than 14 codes (including sub-states like 10081, 10082). Missing even one could cause "cancelled-merged" to be treated as "cancelled", resulting in duplicate inbound.
3. Reserve buffer for incremental window. gmtModified has second-level precision and timezone offset in the source system. The safe approach is to rewind startModified 2-5 minutes earlier to avoid missing boundary data.
4. subTradeId is the detail idempotency key. After flattening, use the combination of "primary key + subTradeId" for deduplication, which is much more reliable than using tradeAfterId alone.
5. Amount allocation fields need secondary verification. shareShouldReturnFee may have rounding differences in the source system, and the total occasionally deviates from the master table amount by 0.01 yuan. It's best to perform tail difference absorption before landing.
6. flagNames needs to be split before use. Multiple business marks are concatenated with delimiters. Don't directly use it as a dimension field. Split it into multi-value fields before participating in filter logic.

Pitfall Retrospective

• Pitfall 1: Details being compressed into empty arrays. A retail company's first version of the integration solution forgot to attach the flattening converter, resulting in only the master table being seen on the Kingdee side, with return quantities always being 0, and inventory write-back being chaotic for a week before being discovered. The safe approach is to immediately sample and verify the number of detail rows after configuration is complete.
• Pitfall 2: Status 10081/10082 being ignored. These two sub-states were not in the old version of the documentation. Engineers directly wrote judgment based on 8-digit status, resulting in "cancelled-merged" orders being treated as normal cancellations, triggering duplicate settlement.
• Pitfall 3: Missing data at incremental boundaries. Aligning gmtModified only by the hour will lose 1-2 changes when pagination crosses the hour mark. It is recommended to rewind the window and add a backfill mechanism.
• Pitfall 4: aa field being mistakenly treated as a business field. This field is essentially a KEY variable placeholder. In one solution, it was mapped by the engineer as a remark on the downstream side, resulting in a large number of "aa" strings appearing on the Kingdee side.
• Pitfall 5: Precision loss in shareShouldReturnFee. Directly mapping the float type to Kingdee's decimal field was truncated to 2 decimal places, resulting in cent-level differences in the total. The safe approach is to explicitly keep 4 decimal places in the mapper.

When to Choose

This interface is suitable for retail, e-commerce, and distribution scenarios with dense after-sales order backflow and strong linkage with ERP financial inventory. When the business only needs an after-sales master table overview and does not involve detail landing, other lightweight interfaces can be considered. When the business needs real-time single-record query rather than batch synchronization, the paginated interface is not the optimal choice.