Authoritative Tutorial on Kingdee Cloud Sales Outbound Order Query Interface (Row-by-Row Mode)

What This Interface Solves

In the supply chain of retail and e-commerce enterprises, Kingdee Cloud handles financial and inventory bookkeeping, while Guanyi Cloud manages front-end orders and shipments. The critical link between them is the "Sales Outbound Order": once a shipment is completed in Guanyi, the warehouse needs to generate an outbound voucher in Kingdee, and in return, tracking numbers, shipping addresses, and outbound details must flow back to Guanyi for reconciliation. The row-by-row query mode of executeBillQuery (FormId=SAL_OUTSTOCK) is the data source for this chain, enabling downstream systems to stably pull incremental outbound data at the line-item granularity.

Interface Capabilities Overview

• Authentication: Based on username/password and data center authorization for Kingdee Cloud private deployment, using the API gateway to call executeBillQuery.
• Request Method: POST, with a fixed form ID of SAL_OUTSTOCK (Sales Outbound Order).
• Field Keys: Declared on demand via the FieldKeys collection, such as FEntity_FENTRYID, FCustomerID.FNumber, FMaterialID.FNumber, etc.
• Filter Conditions: FilterString defaults to incremental by approval date, typically written as FApproveDate>='{{LAST_SYNC_TIME|datetime}}', and can be combined with business conditions like FBillNo, FStockOrgId.FNumber.
• Pagination Parameters: Limit controls the maximum number of rows per request (recommended 2000–5000), StartRow is the starting row index, and TopRowCount defaults to 0. In Kingdee's row-by-row mode, you must paginate through all pages before moving to the next window.
• Response Structure: Returns a collection of detail lines. In metadata, id points to FEntity_FENTRYID, number points to FBillNo, idCheck: true enables primary key validation, and autoFillResponse: true auto-fills response fields.

Typical Field Mappings

How to Configure in Qeasy Cloud

In the Qeasy Cloud data integration platform, the encapsulation of this interface is straightforward: the platform has a built-in Kingdee Cloud adapter, and you only need to fill in the private deployment's access address, account, and data center ID to get an out-of-the-box executeBillQuery call capability.

• Data Source Configuration: Select the "Kingdee Cloud" adapter, fill in the private gateway and authentication information, and the platform will automatically maintain tokens and retries.
• Metadata Mapping: In the Qeasy Cloud field mapper, point metadata id to FEntity_FENTRYID and number to FBillNo, and the platform will automatically enable primary key validation and response field auto-completion.
• Filtering and Pagination: Use platform variables LAST_SYNC_TIME, PAGINATION_PAGE_SIZE, PAGINATION_START_ROW to assemble FilterString, and Qeasy Cloud will iterate through all pages automatically.
• Scheduling Strategy: Recommend a daytime high-frequency, nighttime pause window like */5 7-23 * * *, and Qeasy Cloud's scheduler will automatically handle missed-run compensation and failure alerts.
• Empty Write Strategy: This interface is a pure query strategy, so configure the Target as "empty write operation", and Qeasy Cloud will skip downstream writes and only produce data streams for other strategies to subscribe.

Cross-Solution Practical Points

1. Row-by-row mode must deduplicate by line primary key: FEntity_FENTRYID is the only unique identifier at line granularity; FID will appear duplicate during pagination. Never mix them up.
2. Choose FApproveDate rather than FDate as the incremental cursor: FDate can be un-approved/modified, so using FApproveDate ensures stable incremental syncing without missing orders.
3. Page size should match Kingdee performance: Empirically, 2000–5000 rows per page is most stable; exceeding 10,000 easily triggers timeouts and memory pressure on the Kingdee side.
4. Document type must participate in routing: B2C, retail, consignment, and VMI are completely different in financial and inventory accounting. After getting FBillTypeID_FNumber, branch processing is recommended immediately.
5. Choose FThirdEntryId as the cross-system reconciliation anchor: It is the Guanyi order number, one-to-one mapped with shipment details, and is a natural bridge for logistics writeback and refund offsetting.
6. Minimize transmission of privacy fields: Fields like consignee name, mobile, and address should be trimmed on demand and masked on the landing side to avoid compliance risks.

Pitfall Review

1. Using FID as the primary key causes duplicate imports: Row-by-row query returns a collection of detail lines, where FID is the same for every line, causing duplicate imports. The safe approach is to explicitly point metadata id to FEntity_FENTRYID.
2. FDate incremental cursor eaten by un-approval: When the business side un-approves and modifies the outbound date, incremental syncing by FDate breaks. We later standardized on FApproveDate for stability.
3. Pagination parameters exceeding bounds cause interface timeout: An aggressive configuration of 50,000 rows per page timed out directly in the Kingdee private environment. The safe approach is to keep Limit between 2000–5000 and set reasonable pagination intervals.
4. B2C and standard outbound amounts mixed: B2C outbounds are usually tax-inclusive and settled via e-commerce, and not separating document types causes serious gross margin distortion. Be sure to branch processing after getting FBillTypeID_FNumber.
5. Carrier/tracking number writeback lost: FCarriageNO overwrites old values after multiple logistics modifications. Writeback to Guanyi needs version control, otherwise old tracking numbers may overwrite new ones.

When to Use

Applicable scenarios: Need to sync Kingdee sales outbound data to Guanyi or other downstream systems at the line-item granularity for reconciliation, logistics writeback, and e-commerce order association. Not applicable for: Document writeback (should use save/approve interfaces), real-time single-document query (should use the document detail interface), or cross-entity multi-account-set mixed queries (requires splitting data sources).