Kingdee Cloud Sales Order Query Interface Field Manual: executeBillQuery Practical Tutorial

What This Interface Solves

In the supply chain integration scenario between WDT (WangDianTong) and Kingdee Cloud, sales orders are the core business object. This interface (executeBillQuery, FormId: SAL_SaleOrder) is used to batch query unclosed sales orders from Kingdee Cloud, serving as the source data for downstream synchronization strategies (e.g., "Kingdee Sales Order > WDT Sales Order"). Typical use cases include order master data sync, status tracking, and cross-system reconciliation.

Interface Capability Overview

• Authentication: Standard Kingdee Cloud API authentication, requiring data center account and third-party system authorization.
• Request Method: POST, calling the executeBillQuery interface.
• Request Parameters: Passed via otherRequest, including FormId (fixed as SAL_SaleOrder), FilterString, Limit (default 2000), StartRow (default 0), FieldKeys, etc.
• Response Structure: Returns a flattened wide table from the master and detail tables, with each record corresponding to one order line item.
• Incremental Mode: Achieves incremental filtering by approval date via FApproveDate>='{{LAST_SYNC_TIME|dateTime}}' in FilterString.
• Pagination Mode: Loops based on Limit + StartRow until returned rows are less than Limit.
• Filter Rule: Fixed FCloseStatus='A' to query only unclosed orders.
• Scheduling: Typically configured to run every 5 minutes during 6:00–22:00.

Typical Field Mapping

How to Configure on Qeasy

On the Qeasy data integration platform, the Kingdee Cloud sales order query is typically encapsulated through the "Kingdee Cloud Adapter". This adapter has built-in executeBillQuery calling templates. When configuring, you only need to specify the FormId SAL_SaleOrder, and the platform will automatically construct the request body.

Key Configuration Steps:

1. In Qeasy's "Data Source" management, select the Kingdee Cloud adapter and fill in the data center address and authorization credentials.
2. Create a new scheme in "Query Strategy" with strategy type QUERY_ONLY.
3. Set the FilterString template: FApproveDate>='{{LAST_SYNC_TIME|dateTime}}' and FCloseStatus='A'.
4. In metadata, map id to FSaleOrderEntry_FEntryID and number to FBillNo.
5. Configure Target as "Write Empty Operation", indicating this is a pure query strategy without writing to the target system.
6. Configure the scheduled task: crontab */5 6-22 * * *, polling every 5 minutes.

Qeasy's field mapper automatically recognizes the flattened structure returned by Kingdee and marks primary keys and numbers based on the id/number fields in metadata, making it convenient for downstream strategies to reference.

Cross-Scenario Practical Points

From multiple customer projects, we have distilled the following common experiences:

1. Primary Key Hierarchy Must Be Clearly Distinguished: FID is the bill-level primary key, while FSaleOrderEntry_FEntryID is the line-level primary key. If downstream needs line-item granularity (e.g., shipping, invoicing), use the line-level key; for order-level aggregation (e.g., reconciliation), use the bill-level key and deduplicate.

2. FBillNo Is the Bridge for Cross-System Reference: Kingdee's FBillNo usually has a clear business mapping relationship with WDT order numbers. In Qeasy's mapper, FBillNo should be prioritized as the association key rather than FID (the latter is Kingdee's internal code, unrecognizable by external systems).

3. FilterString Incremental Logic Needs Boundary Testing: FApproveDate is the approval date, not the creation date. If the business relies on creation time to trigger synchronization, you need to add an additional FCreateDate condition, otherwise there will be delays.

4. Pagination Parameters Should Be Set Stably: Limit=2000 is an empirical value—too large causes timeouts, too small increases request count. On Qeasy, it is typically used in conjunction with breakpoint resume mechanism.

5. Memory Overhead of Flattened Results: When there are many order lines, the number of records in the flattened wide table = number of orders × average lines per order. In one retail enterprise's actual test, a single fetch with 2000 rows limit corresponds to about 300–500 orders, requiring downstream processing capacity estimation.

6. Close Status Semantics Are Not Just 'A' and 'B': Kingdee may also have 'C' (manually closed) and other statuses. This strategy retains only 'A' via FilterString, but if downstream needs to analyze closed orders, a separate query strategy must be built.

Pitfall Review

Pitfall 1: Using FID as Cross-System Association Key Causing Reconciliation Failure A customer used Kingdee's FID (e.g., numeric internal code) as the association key with WDT orders, resulting in WDT being unable to recognize it. The reliable approach is to use FBillNo (business document number) as the association key, with FID used only for internal Kingdee deduplication.

Pitfall 2: Ignoring Flattened Structure Causing Data Inflation Downstream strategies mistakenly assumed each record was an order, when in fact each was a line item. As a result, the same order was processed multiple times. The reliable approach is to clearly define id in metadata as the line-level primary key and perform order aggregation downstream.

Pitfall 3: Incremental Filter Missing Approval Date Boundary Orders during a sync window with approval time exactly crossing the hour boundary were missed for two syncs. The reliable approach is to add FApproveDate<='{{CURRENT_TIME|dateTime}}' in FilterString to ensure no boundary data is missed.

Pitfall 4: Overly Strict FCloseStatus Filter Causing Downstream Data Loss Business reported that some shipped-but-not-closed orders were not synced. Investigation revealed that Kingdee's 'A' status definition varies slightly across versions. The reliable approach is to manually execute queries in Qeasy's debug mode to confirm returned data meets expectations.

Pitfall 5: Scheduling Window Coverage Incomplete Crontab configured as */5 6-22 * * * resulted in orders approved after 22:00 not being captured in time for incremental sync. The reliable approach is 24-hour polling, or manually triggering a full reconciliation before market opening the next day.

When to Use

This interface is suitable for supply chain integration scenarios where Kingdee Cloud serves as the ERP master data source and sales orders need to be synchronized to external systems (WDT, WMS, TMS, etc.). It is the preferred solution when the business requires line-item granularity processing (e.g., per-line shipping), relies on approval-date incremental sync, or needs flattened wide tables for quick downstream writes. If real-time push (second-level latency) is needed, consider switching to Kingdee's real-time message queue interface.