Kingdee Sales Outbound Order executeBillQuery Interface Field Manual & Cross-Scenario Tutorial

What Problem Does This Interface Solve

The Kingdee Cloud "Sales Outbound Order executeBillQuery" interface is used to batch-pull outbound delivery data based on business conditions. The typical scenario is reconciling orders from e-commerce/Jushuitan with outbound orders in Kingdee, tracking the to-be-confirmed receipt status, and providing a data source for subsequent status write-back. It solves the "can't find, can't find accurately, can't find completely" problem in cross-system outbound order synchronization and is the core query entry point for the Jushuitan ↔ Kingdee supply chain integration.

Interface Capability Overview

• Authentication: Kingdee Cloud's standard OAuth/account-set authorization, requiring parameters such as acctId, appId, appSecret; the request header must carry a token.
• Request Method: POST, API is executeBillQuery, FormId is fixed as SAL_OUTSTOCK (Sales Outbound Order).
• Request Body: Based on the otherRequest structure, with core parameters including FormId, FieldKeys, FilterString, Limit, StartRow, TopRowCount.
• Response Structure: Returns a Result array, with each row containing key-value pairs of the requested fields; with autoFillResponse:true in metadata, the system auto-fills response fields.
• Pagination/Incremental Mode: Pagination is implemented via StartRow + Limit (Limit defaults to 10000). There is no built-in incremental field; typically FDate or the receipt confirmation date is used as a soft incremental cursor.
• Filter Logic: Default F_QKMS_QRSHRQ is null and FCreatorId.FName='传单专用' and FThirdBillNo <> '', i.e., "to-be-confirmed receipt + created by transmission-dedicated account + internal order number non-empty".

Typical Field Mapping

In Qeasy, the field mapper automatically flattens FCreatorId.FName into a flat field, eliminating the need to write nested parsing scripts; meanwhile, the platform provides type-tolerant handling for FThirdBillNo, but it is still recommended to standardize as string at the source.

How to Configure on Qeasy

1. Adapter Selection: Qeasy has a built-in Kingdee Cloud executeBillQuery adapter; select FormId SAL_OUTSTOCK, and the platform auto-generates the request skeleton and paginator.
2. Metadata Configuration: Set both number and id to FBillNo, enable idCheck:true for primary key validation, buildModel:true to build the data model.
3. Filter Conditions: Write directly in Qeasy's "Filter Expression": F_QKMS_QRSHRQ is null and FCreatorId.FName='传单专用' and FThirdBillNo <> '', the platform will assemble it into FilterString.
4. Field Mapper: Drag the fields listed in FieldKeys into the mapping panel; Qeasy's field mapper auto-builds the source→target field table; selecting "Write Empty Operation" on the Target side makes it a pure query strategy.
5. Scheduling: The cron task is written as 1-59/30 7-23 * * *, executing every 30 minutes between 7–23 o'clock; Qeasy's scheduler triggers automatically per this cron.

Cross-Scenario Practical Points

• Prefer FBillNo as the business primary key: FID is the system primary key and unreliable for cross-system reconciliation; FBillNo is unique and stable on the Kingdee side.
• Filter Condition Trio: "To-be-confirmed receipt + transmission-dedicated + internal order number non-empty" is the minimum set verified by multiple customers; missing any one will pull dirty data.
• Incremental Cursor: FDate vs. Receipt Confirmation Date: Use FDate as soft incremental for high-frequency polling; use F_QKMS_QRSHRQ transitioning from empty to non-empty for event-driven.
• Don't guess the pagination size: The default Limit=10000 is the stable upper limit on most Kingdee instances; exceeding it triggers interface truncation or timeout.
• Type compatibility must be solved at the source: FThirdBillNo is int in the source config, but Jushuitan order numbers often contain letters; do type conversion before integration.
• Target Configuration for Pure Query Strategies: Select "Write Empty Operation" for Target, meaning this strategy only pulls data, and subsequent write-back actions are handled by downstream strategies.

Pitfall Retrospective

• Pitfall 1: Inconsistent FThirdBillNo Type. Source configured as int, but the actual order number contains letters, the interface errors out directly or returns null. The safe approach is to uniformly handle as string at the source, or force type conversion in Qeasy's field mapper.
• Pitfall 2: Filter Condition Missing FCreatorId. Only writing "receipt confirmation date is empty" will pull outbound orders from all channels, making them un-linkable on the Jushuitan side. Be sure to add FCreatorId.FName='传单专用' to the filter.
• Pitfall 3: Treating FID as the Business Number for Reconciliation. FID is the database primary key and changes across account sets or organizations; reconciliation must use FBillNo.
• Pitfall 4: Pagination Out-of-Bounds. When Limit exceeds 10000, Kingdee silently truncates, and the data appears complete but loses the tail. Qeasy's paginator has built-in safety limits, but you still need to be careful with custom scripts.
• Pitfall 5: Scheduling Window Missing Night Orders. The cron 7-23 misses early-morning orders, which is easy to flip over when adding new strategies; if the business spans overnight, the safe approach is to expand the window to 0-23 or split into two segments.

When to Use

This interface is suitable for medium-to-large retail enterprises where "Kingdee creates orders and Jushuitan handles orders," requiring batch querying of sales outbound orders by business conditions and reconciling with upstream orders or writing back statuses. Boundary: it is query-only and does not handle writes; if writing into Kingdee, switch to save/submit-type interfaces; if real-time push is needed, pair with a message middleware rather than pure polling.