Authoritative Tutorial: Jikeyun Refund Order Query API Field Handbook

What This Interface Solves

In the supply chain integration between Jikeyun and Kingdee Cloud Flagship, refund order synchronization is often overlooked yet carries high risk. If compensation refund data is not promptly pushed back to Kingdee, it will cause imbalanced sales order amounts, incorrect accounts receivable, and missing refund vouchers. This interface (ass-business.refund.listRefundInfo) is specifically designed to query full refund order data from the Jikeyun side, distinct from the return/change (returnchange) interface, and focuses purely on compensation refund scenarios, providing a data source for generating Kingdee red-letter sales orders or refund vouchers downstream.

Interface Capability Overview

• Authentication: Jikeyun Open Platform OAuth/AppKey signature authentication; private deployments require an internal gateway address.
• Request Structure: POST request with JSON body. Core parameters include pageIndex (default 0), pageSize (default 200, max 1000), tradeNo, refundNoList, refundStatusList, startTime/endTime, startModified/endModified.
• Response Structure: Returned data is wrapped in the refundList array. Each element contains master fields plus four nested objects: payInfo, receiverInfo, refundGoodsItems, and customColumnInfo.
• Pagination and Incremental: Supports pageIndex pagination and incremental queries by gmtModified. For incremental queries, use startModified/endModified rather than creation time to avoid missing records.
• Operation Type: Pure query (QUERY_ONLY), with Target configured as a write no-op, commonly used in scheduled fetching tasks.

Typical Field Mapping

How to Configure on Qeasy Cloud

In the Qeasy Cloud data integration platform, this interface has been encapsulated as a standard adapter. The typical configuration path is: Integration Source → Jikeyun → Select "Query Refund Order" Template. The platform will automatically inject request parameter templates and paginators, and engineers only need to confirm refundId as id and refundNo as number in metadata.

For Kingdee-side sales order association, Qeasy Cloud's field mapper supports the _findCollection expression: reverse lookup billno in the Kingdee sales order collection by tradeNo, and automatically write to salesOrderId. For nested fields like payInfo.returnTotal with dotted paths, Qeasy Cloud's field mapping panel can directly expand the nested structure, completing mappings without writing scripts.

For scheduling, the platform defaults to crontab */30 * * * * to fetch every 30 minutes, combined with the gmtModified watermark field for incremental sync. If cross-timezone issues arise, set the source system timezone to Asia/Shanghai in the platform timezone configuration.

Cross-Scenario Best Practices

1. Refund orders and return/change orders must be modeled separately: The refund order primary key is refundId, while the return/change order primary key is tradeAfterNo. Mixing them causes semantic confusion in amount fields.
2. Associated sales order number is the bridge to Kingdee: Jikeyun's tradeNo corresponds to Kingdee sales order's billno, and this mapping is the core of cross-system reconciliation.
3. Nested object payInfo is key to amount validation: payInfo.returnTotal should equal the sum of refundFee in refundGoodsItems; always include this check during reconciliation.
4. Incremental field must use gmtModified, not gmtCreate: Refund orders undergo multiple modifications (audit, status change); pulling only by creation time will miss status updates.
5. Store dimension needs separate handling: In multi-store/multi-channel scenarios, shopCode should serve as a data isolation dimension to avoid mixing refund orders from different channels.
6. Refund line item count may be 0: In pure refund without return scenarios, refundGoodsItems may be an empty array; handle empty array compatibility when writing downstream.

Pitfall Retrospective

• Pitfall 1: Using tradeNo as the primary key causes duplicate imports: tradeNo is the sales order number, and a single sales order may generate multiple compensation refund records. The primary key must be refundId. The reliable approach is to explicitly declare the id field as refundId in metadata.
• Pitfall 2: Timezone inconsistency causes incremental record misses: gmtModified in the source system is UTC+8; if the integration platform parses as UTC, records within the 8-hour window will be missed. Always confirm the source system timezone and configure watermark conversion.
• Pitfall 3: refundGoodsItems and goodslist duplication: The two fields may carry different serializations of the same product details; map only one, otherwise downstream deduplication logic becomes chaotic.
• Pitfall 4: Filtering before confirming enum values: If refundStatusList parameters are passed based on guessed enum values, status filtering will yield no data. Recommend pulling all data for the first 1-2 schedule cycles, confirming enums, then enabling filtering.
• Pitfall 5: Missing bank fields within payInfo: For some refund orders, payInfo.bankName and bankCode are empty. If non-null validation is too strict during mapping to Kingdee, writes will fail. Add default values or allow null values in the mapper.

When to Use

This interface is suitable for private deployment integration scenarios where Jikeyun serves as the e-commerce middle platform and integrates with Kingdee Cloud Flagship for supply chain-financial integration. It is particularly applicable when generating red-letter sales orders or refund vouchers from refund orders and requiring strong association reconciliation with original sales orders. When the business scenario involves return/exchange receiving, the return/change order interface should be used instead of the refund order interface.