Kingdee Cloud Skyline Terminal Customer Auxiliary Data Query API Field Manual

What This Interface Solves

In supply chain integration between Kingdee Cloud Skyline and Weaver OA-E9Http, terminal customer (auxiliary data category ZDKKH) is a commonly used classification dictionary in customer master data, sales orders, and customer archives. This interface uses executeBillQuery to page and batch-pull audited terminal customer dictionary items, supporting scenarios such as OA approval flow mapping against Kingdee customer classifications, and customer attribute mapping. The Target is configured as a "null write operation", positioning this strategy as a pure query strategy, allowing downstream sync tasks to consume the results.

Interface Capability Overview

• Authentication:Kingdee Cloud Skyline WebAPI protocol, typically using application-level AppId/Secret signature, with the endpoint path executeBillQuery.
• Request Structure:FormId is fixed as BOS_ASSISTANTDATA_DETAIL, Filter is fixed as FId.FNumber in ('ZDKKH') and FDocumentStatus='C', and returned columns are controlled through FieldKeys.
• Response Structure:JSON array, where each record corresponds to one auxiliary data detail entry, and the primary key is FEntryID.
• Pagination/Incremental Mode:Adopts Limit + StartRow offset pagination. Typical Limit=1000, and StartRow is dynamically injected through the {{PAGINATION_START_ROW}} placeholder, which the platform calculates automatically based on the previous response count.
• Scheduling Strategy:In real projects, a crontab of */8 7-23 * * * is typically used, with high-frequency polling during the day and idle at night.

Typical Field Mapping

How to Configure on Qeasy Cloud

On the Qeasy Cloud Data Integration platform, this interface typically adopts a combination of "Kingdee Cloud Skyline Query Adapter + Null Operation Write Adapter":

• Adapter Selection:Select the Kingdee Cloud Skyline executeBillQuery adapter for the source. FormId is preset to BOS_ASSISTANTDATA_DETAIL, and the Filter expression can be reused directly.
• Paginator:The platform's paginator automatically manages StartRow and Limit, advancing to the next page based on the returned count after each call, and determining completion upon empty response.
• Field Mapper:Qeasy Cloud's field mapper automatically generates the target field list according to FieldKeys. FNumber and FDataValue are usually mapped to terminal_customer_code and terminal_customer_name.
• Null Operation Target:Choosing "Null Operation" as the Target represents pure query mode. Results are temporarily stored in the platform's transit area for subsequent strategies to consume, or can be pushed directly to the data warehouse.
• Scheduler:The crontab expression can be configured visually in the platform's scheduling panel, no manual writing required.

Cross-Strategy Practical Points

1. Filter conditions must be double-locked:Simultaneously filter FId.FNumber in ('ZDKKH') and FDocumentStatus='C' to avoid pulling back unaudited or non-category dirty data.
2. FNumber as the golden association key:In multiple supply chain solutions, cross-system matching prioritizes FNumber over name, because names can be changed while codes remain stable.
3. FForbidStatus cannot be ignored:Even if the document is audited, forbidden (F) dictionaries may still be distributed to business systems. In real scenarios, an additional layer of filtering is required.
4. Page size should not be too large:Limit=1000 is a stable choice. Excessive values may trigger Kingdee gateway timeouts; in multi-org scenarios, the value can be moderately reduced.
5. Multi-org distinction depends on FUseOrgId:The same code may have different meanings under different organizations. When distributing downstream, be sure to split by usage organization.
6. Audit fields should be used cautiously:Fields such as FCreateOrgId, FUseOrgId, and FDescription should not serve as master data mapping basis, only for traceability.

Pitfall Retrospective

• Pitfall 1: Name changes causing downstream misalignment. A retail enterprise once had sales departments directly change FDataValue in Kingdee, while the downstream OA still matched by name, resulting in classification chaos. The safe practice is to always use FNumber as the association key, with names used only for display.
• Pitfall 2: Unaudited data being pulled. If the hard filter FDocumentStatus='C' is forgotten, a large amount of draft dictionaries will appear, generating double versions after subsequent activation. Be sure to write it explicitly in the Filter.
• Pitfall 3: FEntryID and FID mixed up. The entry-level primary key FEntryID and the master-level primary key FID differ greatly in cross-table association. Some solutions once treated them as the same field for deduplication, resulting in missed records. Choose according to business granularity.
• Pitfall 4: Pagination infinite loop. When an empty array is returned without timely termination of pagination, infinite loop pulling will occur. In Qeasy Cloud, the paginator usually determines termination automatically, but custom script solutions need to determine explicitly.
• Pitfall 5: Forbidden dictionaries still in use. If audited dictionaries with FForbidStatus='F' are distributed as usual, "ghost options" will appear in business system dropdowns. It is recommended to add a conditional filtering step in the Qeasy Cloud field mapper.

When to Choose

Applicable scenarios:In supply chain integration, it is necessary to pull auxiliary data dictionaries such as terminal customers, sales channels, and customer attributes from Kingdee Cloud Skyline, and synchronize them to OA, CRM, or data warehouse. Boundary:This strategy only applies to the auxiliary data detail table, not directly querying the customer archive master table; if real-time single-item query is required, switch to executeBillQueryById or view interfaces.