Authoritative Tutorial on Kingdee Cloud Skylight Material Query Interface Field Handbook (Supply Chain Master Data Integration)

What This Interface Solves

In retail e-commerce and ERP unified scenarios, material/product master data is the foundation for all supply chain documents such as sales, purchasing, inventory, and transfers. We often need to sync material master data from the ERP to front-end systems, or reversely verify whether written records are correct. The executeBillQuery (Query Kingdee Material) interface is designed to paged-pull approved material master records by modification time, serving as the core entry point for bidirectional material master sync and post-write validation.

Interface Capability Overview

• Authentication: Kingdee Cloud Skylight OAuth2.0 / application secret dual-factor authentication. In the Qeasy adapter, this is encapsulated as a unified credential configuration panel, requiring no manual token exchange logic.
• Request Structure: POST to the executeBillQuery endpoint with FormId fixed as BD_MATERIAL, combining filter conditions via FilterString, typically FUseOrgId='7000' AND FDocumentStatus='C' AND FModifyDate>='{{last_run_time}}'.
• Response Structure: Kingdee's standard Result → Rows array, where each Row is a set of key-value field pairs, and related objects are returned in the field.sub-property format (e.g., FBaseUnitId.FNumber).
• Pagination/Incremental Mode: Cursor pagination based on Limit and StartRow, combined with FModifyDate for incrementality; Qeasy defaults to 2000 records per page, auto-rolling cursors by modification time, with breakpoint resumption managed by the platform.
• Scheduling Cadence: Strategy-level crontab 1-59/5 7-23 * * *, running every 5 minutes during working hours with reduced frequency at night.

Typical Field Mapping

How to Configure on Qeasy

• Adapter: Qeasy has a built-in "Kingdee Cloud Skylight executeBillQuery" adapter; just fill in AppId/AppSecret/tenant credentials. Select BD_MATERIAL as the FormId, and the platform automatically injects pagination and incremental cursors.
• Field Mapper: The platform automatically identifies FMasterId as id and FNumber as number. Other fields are expanded via the field_sub-property syntax (e.g., FBaseUnitId.FNumber → FBaseUnitId_FNumber). Qeasy's field mapper automatically generates the target column structure without manual JSON.
• Filter Template: Built-in "by modification time incremental" template, just configure use organization and approval status constants.
• Target Configuration: This type of pure query strategy selects "Write No-Op" as Target, with the chain only running extraction and landing to the intermediate database.
• Scheduling: The platform provides a visual crontab editor, equivalent to expressions like 1-59/5 7-23 * * *.

Cross-Project Practical Points

1. Use FMasterId+FNumber as composite primary key: In real scenarios, relying solely on FNumber causes collisions in cross-org contexts; dual-writing primary key and code is more robust.
2. Must filter FDocumentStatus='C': Field values of materials in pending/draft state are volatile, pulling them in pollutes downstream.
3. Incremental cursor must be persisted to reliable storage: Qeasy defaults to storing the FModifyDate last value to the strategy state table; do not let the target side overwrite it.
4. Related object fields need secondary expansion: FBaseUnitId.FNumber does not auto-flatten; either use the mapper renaming rules or explicitly split in scripts.
5. Unify units and numeric field conversion: Length/weight often carry ERP units and must be aligned with the unit dictionary before being written to front-end SKUs—this is the easiest place to fail.
6. Validate after write enablement: The practice behind "Data Write After Enablement" means the query strategy runs empty before the write strategy, confirming no duplicates before officially running the chain, minimizing regression cost.

Pitfall Recap

• Pitfall 1: Not filtering approval status caused downstream to receive draft-state materials, triggering inventory archive creation failure. Fix: Force FDocumentStatus='C' in FilterString and tick "Approved Only" in Qeasy filter templates.
• Pitfall 2: Using related fields directly as strings: The full FBaseUnitId return is an object; without expansion it writes a JSON string into the database. Fix: Use Qeasy field mapper's _FNumber expansion rule to auto-flatten.
• Pitfall 3: Incremental time window regression: Server clock drift caused some records to be missed. Fix: Add a 5-minute regression tolerance to the incremental cursor in Qeasy to avoid boundary loss.
• Pitfall 4: Multi-org material duplication: Pulling without FUseOrgId filter caused cross-org materials to be written multiple times. Fix: Fix the use organization in the strategy, or split strategies by org dimension.
• Pitfall 5: Scheduling period overlapping nightly batch processing: 5-minute polling colliding with ERP nightly closing caused slow or even timed-out responses. Fix: Reduce frequency at night, restore high frequency during the day; the platform provides time-slot scheduling configuration.

When to Use

Applicable scenarios: ERP ↔ front-end system material master bidirectional sync, post-write consistency validation, cross-org material distribution, batch material pulling for cold start of new systems. Not applicable: Real-time single-record queries (use the document detail interface), draft-state material collection, and sync of non-BD_MATERIAL business objects.