Authoritative Tutorial on the Kingdee Material Query Interface: Aggregated Field Manual Across Integration Scenarios

What This Interface Solves

In supply chain integration, material master data is the foundation of every downstream flow—purchasing, sales, inventory. We need to continuously and reliably synchronize Kingdee Cloud materials to external systems (Guanyi products, 聚水潭 products, etc.) for code mapping, document line material mapping, and price/inventory retrieval. This interface acts as a "unified material exit" from Kingdee: a single query strategy supports multiple downstream consumers, avoiding repeated polling.

Interface Capability Overview

• Authentication: Kingdee Cloud WebAPI (AppId + AppSecret + AcctID), pre-configured in the connector.
• API: executeBillQuery, HTTP POST, QUERY semantics (read-only).
• FormId: fixed as BD_MATERIAL (material master).
• Request parameters: FieldKeys (field whitelist), FormId, FilterString (filter condition), Limit (default 2000), StartRow (pagination start, typically {{PAGINATION_START_ROW}}), TopRowCount (default 0 means return total count).
• Response structure: JSON array; each row contains fields specified by FieldKeys; system auto-fills metadata fields like FMasterId, FNumber.
• Pagination and incremental: based on Limit + StartRow; incremental sync depends on FilterString, typically FModifyDate>='{{LAST_SYNC_TIME|dateTime}}'.
• Schedules: two common rhythms — */5 7-23 * * * (high-frequency, every 5 minutes) and */10 8-21 * * * (business hours, every 10 minutes), chosen based on data volume and downstream capacity.
• Target: configured as "WriteEmpty"—a pure query strategy whose output is consumed by downstream strategies.

Typical Field Mappings

How to Configure on Qeasy

In the Qeasy Data Integration Platform, this interface is typically encapsulated as a visual data source via the "Kingdee Cloud Query Adapter":

1. Connector: fill in Kingdee App ID/Secret, account code, internal domain (for private deployment); supports private gateway proxy.
2. Data Source (Strategy Source): select adapter kingdee.executeBillQuery, choose FormId BD_MATERIAL.
3. Field Mapper: the platform auto-reads the response structure and generates the default FieldKeys list; Qeasy's field mapper supports visual field selection/deselection, and automatically injects FMasterId into id and FNumber into number.
4. Filter and Pagination: reuse {{LAST_SYNC_TIME|dateTime}} for the FilterString template; bind StartRow to {{PAGINATION_START_ROW}}.
5. Metadata: write metadata.id = FMasterId, metadata.number = FNumber, idCheck = false, autoFillResponse = true into source metadata so downstream write strategies can consume with zero cost.
6. Target: select "WriteEmpty" to mark this strategy as query-only, no target writes.
7. Schedule: paste */5 7-23 * * * or */10 8-21 * * * in the strategy schedule.

Cross-Scenario Practical Points

1. Separate query and write strategies: across multiple client projects, we always isolate "Kingdee material query" as an independent strategy with empty target; downstream consumers subscribe on demand, avoiding repeated Kingdee calls.
2. Encapsulate required fields uniformly: required conditions like FMaterialGroup_FNumber, FErpClsID, FCategoryID, FUseOrgId_FNumber should be pre-bound in Qeasy's default parameter set to minimize script errors.
3. FilterString as incremental watermark: the stable approach is using FModifyDate as the incremental key and maintaining LAST_SYNC_TIME state in Qeasy; for historical backfill, switch to conditional retrieval instead of relying on incremental.
4. Multi-org isolation first: under Kingdee's multi-org architecture, always pass FUseOrgId_FNumber as a query condition to prevent cross-org data leakage.
5. Cross-system primary matching key selection: in B2C scenarios (Guanyi/聚水潭), prefer FNumber; for legacy system migration, use FOldNumber as fallback; the extension field F_UQRW_Text suits idempotent linkage code.
6. E-commerce extension fields must be aligned: F_PAEZ_Base2, FBARCODE, FMnemonicCode vary across clients; in Qeasy's field mapper, they should be selected per target system.

Pitfall Retrospective

1. Missing required fields yield 0 rows instead of errors: when any required condition like FUseOrgId_FNumber or FErpClsID is missing in FilterString, Kingdee returns an empty set rather than an error, which is easy to misdiagnose. The stable approach is putting them into Qeasy's default parameters to avoid script-level omission.
2. Limit and pagination boundaries: 2000 seems enough, but with materials exceeding tens of thousands, multiple round trips occur; if StartRow is not taken from {{PAGINATION_START_ROW}}, you'll fall into infinite loops or miss pages. Always use the platform pagination variable.
3. Cost of idCheck = false: without primary key validation, if upstream renames fields or returns empty, platform deduplication will fail. Acceptable short-term, but enable it explicitly in production.
4. Time-zone drift on incremental field: when FModifyDate and LAST_SYNC_TIME timezones differ, data loss or duplication occurs. In real scenarios, we align via UTC offset or Kingdee server timezone.
5. E-commerce extension fields vary across clients: F_PAEZ_Base2, F_UQRW_Text are private extensions in some retail enterprises; when migrating to other clients, field mapping must be redone. Qeasy's field mapper supports one-click renaming—don't hardcode.

When to Choose

Choose this interface when business involves distributing Kingdee Cloud material master data externally (e-commerce, product/warehouse mapping, sales-outbound/purchase-inbound document mapping) with high-frequency incremental sync. Boundary: for one-time initialization, switch to full export; for millisecond-level real-time requirements, use Kingdee database CDC instead of WebAPI polling.