Kingdee Cloud Purchase Return Application Query API Field Manual: From Entries to Return Types, Fully Explained

What This Interface Solves

The Purchase Return Application is one of the core documents in Kingdee Cloud's supply chain domain, carrying the business process of returning materials, replenishing, or deducting payments to suppliers. This API is mainly used to pull return application data from Kingdee into e-commerce or supply chain collaboration systems (such as Wangdiantong), enabling status synchronization, reconciliation, inventory back-flushing, and supplier settlement. It is the key data source for the purchase return closed loop.

Interface Capability Overview

• System: Kingdee Cloud (public cloud deployment).
• Request Method: Typically based on Kingdee Cloud's QueryService (WebAPI/BOS query service), passing FormId and filter conditions.
• Authentication: Kingdee Cloud uses third-party app authorization + API secret signing. When invoked through Qeasy, the platform automatically maintains token refresh and session renewal.
• Response Structure: Header and line fields are returned flatly together — header fields (e.g., FBillNo, FID, FDate) and line fields (e.g., FEntity_FEntryID, FMATERIALID_Fnumber, FMRQTY) are on the same layer. One record = one line entry.
• Pagination / Incremental: Kingdee QueryService supports paging parameters (page index, page size) and incremental timestamp filtering. Integration usually uses FModifyDate as the incremental cursor, polling with Top > LastModifyTime.

Typical Field Mappings

How to Configure on Qeasy

On the Qeasy Data Integration platform, this API is typically called via the Kingdee Cloud adapter. Configuration has four steps:

1. Create a data source: Select Kingdee Cloud, enter tenant info and API secret; the platform automatically completes OAuth authorization and session management.
2. Choose the business object: Drag-and-drop modeling on the "Purchase Return Application" template; FormId, field types, and enumeration dictionaries are pre-built.
3. Configure the field mapper: Qeasy's field mapper automatically matches Fxxx-series fields to the target system (e.g., Wangdiantong). For multiple unit systems (inventory/base/purchase/pricing), it is recommended to fix a base unit via the "Unit Conversion" operator first, then map — this prevents quantity drift downstream.
4. Configure increment and scheduling: Use FModifyDate > ${lastSyncTime} as the incremental condition. Combined with Qeasy's built-in scheduler, quasi-real-time polling is easily achieved.

Cross-Solution Practical Tips

Across multiple retail/e-commerce customer projects, we have repeatedly validated the following:

1. Only sync approved documents: A/B status documents can still be modified in Kingdee, causing downstream data jitter. Enforce FDocumentStatus='C' in the filter.
2. Route by business type before mapping: Standard procurement, subcontracting, and VMI have very different downstream warehouse and settlement logic. Route by FBusinessType first, then map separately.
3. Three quantity sets: return / replenish / deduct: FMRQTY (actual return), FREPLENISHQTY (replenish), and FKEAPAMTQTY (deduct) are mutually exclusive based on FRMMODE — do not sum them.
4. Use FPOORDERENTRYID as correlation key: More stable than FORDERNO; survives doc number reuse or post-modification.
5. Fix unit conversion upfront: One material can exist in inventory, base, purchase, and pricing units. In Qeasy, do a "unified base unit" conversion first, so downstream only sees one number.
6. Incremental cursor must be FModifyDate, not FCreateDate: Return documents are repeatedly modified (added remarks, replenishment changes). Using create time will miss data.

Pitfall Retrospective

• Pitfall 1: Documents modified after approval are missed. Kingdee QueryService sorts by modification time correctly, but if you add FDate to the filter, post-approval modifications will be missed. The safe approach is to filter only by FModifyDate.
• Pitfall 2: Deduction qty misread as return qty. When FRMMODE=B (return and deduct), FKEAPAMTQTY is the field that actually impacts supplier settlement; FMRQTY is only the physical return quantity. Always pick fields by FRMMODE.
• Pitfall 3: Kit parent/child lines are mixed. Lines with FRowType=Parent aggregate child quantities; syncing them directly causes double counting. Skip Parent lines and only sync Son/Standard.
• Pitfall 4: Empty FSTOCKLOCID causes downstream errors. Stock location is optional in Kingdee but required by some downstream systems. Add a default-location fallback rule in Qeasy.
• Pitfall 5: Pagination boundary throws exceptions. Kingdee QueryService returns an empty array (not an error code) when the last page is smaller than pageSize. Schedulers that retry on exception will get stuck in a loop. Qeasy's built-in scheduler treats empty responses as "done" — no extra handling needed.

When to Use

This interface fits the "Kingdee Cloud → e-commerce / supply chain collaboration" one-way return data sync scenario, especially in retail and manufacturing enterprises with multiple organizations and business types (standard procurement, subcontracting, VMI). When the enterprise handles both inspection returns and inventory returns, with subsequent replenishment or deduction settlement, this API is almost the only authoritative source. For pure inventory ledger sync or document archiving, it is not necessary to enable this interface.