Kingdee Cloud Skylus Material Query API Field Handbook: An Authoritative Tutorial from executeBillQuery to Qeasy Implementation

What This API Solves

In supply-chain integration, material master data is the foundation for every sales order, purchase order, inventory transaction, and production document. Kingdee Cloud Skylus's executeBillQuery API (FormId BD_MATERIAL) allows us to pull material records incrementally by modification time and filtered by using organization, with pagination. It serves both as the entry point for the initial bulk sync of materials to edge systems (e-commerce/ERP) and as a "license keep-alive" strategy—periodically waking the Kingdee API connection to prevent license expiration.

API Capability Overview

• Authentication: Kingdee Cloud Skylus API pass (AppId + AppSecret + tenant identifier), centrally managed via Qeasy credential vault.
• Request structure: FormId=BD_MATERIAL, FieldKeys (passed in as a field list), FilterString (organization + incremental conditions), Limit (default 2000), StartRow (pagination cursor).
• Pagination mode: Offset-based pagination using StartRow + Limit. Loop calls are required until the returned row count is less than Limit.
• Incremental mode: FModifyDate>='{{LAST_SYNC_TIME|datetime}}'. Qeasy scheduler persists the last successful timestamp and injects it automatically.
• Response structure: Two-dimensional table + metadata. id comes from FMasterId, number comes from FNumber, and other fields are returned as flat columns.

Typical Field Mapping

How to Configure on Qeasy

On the Qeasy Data Integration Platform, Kingdee Cloud Skylus material queries are typically built using an adapter + field mapper combo:

1. Source adapter: Select "Kingdee Cloud Skylus - executeBillQuery" and fill in credentials and tenant identifier.
2. Query template: FormId is fixed as BD_MATERIAL. FieldKeys can directly reference Qeasy's built-in "Material Field List" to avoid manual typos.
3. Incremental variable: Insert {{LAST_SYNC_TIME}} into FilterString. Qeasy scheduler automatically injects the last successful timestamp—no manual maintenance required.
4. Paginator: The platform defaults to looping with Limit=2000 until an empty result set is returned, then automatically merges downstream.
5. Field mapper: Left side is Kingdee fields, right side is target system fields (e.g., Guanyi Cloud items). The platform supports "auto-expand underscores" and "auto-bind metadata.id/number", so almost no scripting is needed.
6. Target write: For this kind of "license keep-alive" strategy, the Target is usually configured as a "no-op write" that only triggers the query to keep the license active.

Cross-Solution Practical Highlights

1. FilterString must include using organization: In real scenarios, multi-org customers that don't filter will see hundreds of thousands of rows in a single call, stressing both Qeasy memory and the Kingdee server.
2. Incremental timestamps must be ISO8601 with time zone: Kingdee's FModifyDate carries a time zone. Qeasy scheduler auto-aligns, but cross-region customers should explicitly tag +08:00.
3. Pagination cursor uses StartRow, not page numbers: Kingdee pagination is offset-based. Qeasy paginator maintains an accumulating StartRow to avoid missing or duplicating rows.
4. Map primary key and code separately: In metadata, id/number must strictly correspond to FMasterId/FNumber, otherwise downstream inserts will fail on unique constraints.
5. Pass through business switch fields: Don't drop FIsSale, FIsPurchase, etc. in the middle layer, or sales/purchase sync will be rejected for material type mismatch.
6. Configure license keep-alive as a separate strategy: Run the no-op write query on its own schedule (e.g., every 5 minutes) to avoid contending with real sync tasks for license slots.

Pitfall Retrospective

• Pitfall 1: Forgot to constrain FUseOrgId, blew up memory. A retail enterprise's first sync omitted the org filter and pulled 800k rows in a single shot, causing the Qeasy node to OOM. The safe approach is to make using-organization filter the very first condition in FilterString.
• Pitfall 2: Used the wrong pagination variable. Kingdee's pagination parameter is StartRow, not PageIndex. Writing PageNum instead of StartRow traps the loop on the first page.
• Pitfall 3: Mapped id field to FNumber. Metadata id must bind to FMasterId; otherwise all downstream UPSERTs fail.
• Pitfall 4: Incremental time used local time. When the node time zone differs from the Kingdee server, the incremental window shifts by hours. Qeasy scheduler injecting UTC+8 uniformly avoids this.
• Pitfall 5: Forbidden materials flowed downstream. FForbidStatus='B' means forbidden. Not filtering causes sales orders to error out. The safe approach is to add a filter node in Qeasy's field mapper.

When to Use

Applicable scenarios: Kingdee Cloud Skylus is the ERP backbone, and you need to sync material master data to e-commerce / WMS / MES, or periodically keep the Kingdee API license alive. Boundaries: When material volume exceeds tens of millions and real-time sync is required, switch to direct database connection + binlog. If you only need queries without writes, use the "no-op write" mode directly as a license keep-alive.