Authoritative Tutorial on the Material Batch-Enable Query Interface (executeBillQuery) of Kingdee Cloud

What Problem This Interface Solves

In multi-org, multi-ledger Kingdee Cloud + SQL Server supply-chain integrations, teams often need a quick way to locate materials in the e-commerce ledger that have batch management enabled, in order to feed downstream batch inventory, e-commerce order fulfillment, and batch adjustment strategies. By calling executeBillQuery with FormId BD_MATERIAL, this interface filters precisely by use organization, material group, and approval date, returns a read-only result set, and writes nothing to the target system. It is the most common "list-style" feeder strategy in the batch-management domain.

Interface Capability Overview

• Authentication: Standard Kingdee Cloud OAuth / account scheme; in private deployments, traffic goes through an internal gateway. Credentials and ledger info are configured inside the Qeasy Cloud connector.
• Request structure: Built on executeBillQuery, submitting FormId BD_MATERIAL, a FilterString, a field set, and pagination parameters.
• Response structure: Returns a standard Kingdee bill collection with F-prefixed fields such as FMasterId, FNumber, FName, FIsBatchManage.
• Pagination / incremental: Pagination is supported; incremental sync is driven by FApproveDate >= '{{LAST_SYNC_TIME|dateTime}}', with Qeasy Cloud's scheduler maintaining the cursor automatically.
• Strategy type: effect = QUERY with a "write-null" Target — pure query, no writes.
• Schedule: Cron 3-59/5 * * * *, runs every 5 minutes.

Typical Field Mapping

How to Configure It in Qeasy Cloud

In the Qeasy Cloud data integration platform, the wrapper for this interface is very lightweight. Under the Kingdee Cloud connector, create a new strategy, choose API executeBillQuery with FormId BD_MATERIAL, then tick the seven fields above in the visual form — the platform will automatically resolve F-prefixed fields into Chinese labels.

Qeasy Cloud's field mapper will auto-fill id = FMasterId and number = FNumber from metadata, and enable idCheck = true and autoFillResponse = true. FilterString can be edited directly in the platform; common snippets:

• FUseOrgId.FNumber = '100' (lock to the e-commerce ledger)
• FApproveDate >= '{{LAST_SYNC_TIME|dateTime}}' (incremental)
• FMaterialGroup.FNumber IN (...) (scope by group)

Set strategy type to QUERY, Target to "write-null", and schedule to 3-59/5 * * * * to go live.

Cross-Scenario Practical Points

Across multiple client projects of SQL Server + Kingdee Cloud supply-chain integration, we have distilled the following common lessons:

1. "Use organization" is the golden line for the e-commerce ledger. Almost every material strategy must be scoped by FUseOrgId.FNumber, otherwise data from manufacturing or retail ledgers will leak in.
2. FIsBatchManage must act as the downstream switch. E-commerce order, batch inventory, and batch adjustment strategies commonly take this interface's output as their filtered list.
3. Prefer FApproveDate as the incremental field. Compared with FModifyDate, the approval date is more stable and avoids repeatedly pulling draft-state materials.
4. Configure a Target even for pure queries. Choosing "write-null" keeps the strategy observable while preventing accidental writes.
5. Every 5 minutes is the sweet spot. The e-commerce ledger has a low material change frequency; too tight triggers Kingdee's gateway rate limit; too loose hurts downstream freshness.
6. Dual-track primary key and code. Maintain both FMasterId and FNumber, and build two indexes on the SQL Server side to enable comparison by either.

Pitfall Recap

• Pitfall 1: Missing FUseOrgId filter. The direct result is a return of all materials across the group, causing downstream batch inventory to "explode." The safe approach is to hard-code FUseOrgId.FNumber = '100' in the Qeasy Cloud FilterString and to add a sampling check in the scheduler self-test.
• Pitfall 2: Wrong incremental field. One project used FModifyDate, causing pre-approval materials to be pushed repeatedly and duplicate rows in downstream batch inventory. The safe approach is to standardize on FApproveDate; Qeasy Cloud's scheduler advances the cursor based on status change timestamps.
• Pitfall 3: idCheck not enabled. If SQL Server-side codes are manually edited, missing the primary-key check causes data misalignment. Always enable idCheck = true in Qeasy Cloud metadata.
• Pitfall 4: Ignoring the batch field. One downstream strategy ignored FIsBatchManage and treated all materials as batch-managed, leading to anomalies in non-batch material inventory. The safe approach is to filter FIsBatchManage = 'true' at the first step of the downstream chain.
• Pitfall 5: Schedule triggering Kingdee rate limit. Setting the cadence to once per minute tripped the private gateway QPS limit and queries failed. The safe approach is to choose 5 minutes or longer based on the business peak, and stagger multi-strategy schedules to avoid on-the-hour spikes.

When to Use

Applicable: In multi-org Kingdee Cloud + SQL Server supply-chain integration scenarios where you need an incremental, group-scoped, ledger-scoped list of materials with batch management enabled, serving as the pre-filter for downstream strategies such as e-commerce order, batch inventory, and batch adjustment. Boundary: This interface is read-only — it does not write back to the target system; if a write-back is needed, create a separate SYNC strategy. Multi-language, long-text, and attachment-type fields are outside this interface's output.