Authoritative Tutorial on Kingdee Cloud Customer Information Query Interface Field Manual

What Problem This Interface Solves

In the supply chain integration between Jushuitan and Kingdee Cloud, customer master data is the prerequisite for sales outbound orders, return orders, and purchase documents to correctly identify the "consignee." We often encounter scenarios where a customer in Kingdee changes their name or code while Jushuitan still uses the old value, leading to wrong customer assignment on downstream documents and reconciliation discrepancies. By incrementally pulling Kingdee's BD_Customer via executeBillQuery into the middleware, we can unify the code mapping standard and provide an authoritative source for customer mapping in subsequent business documents.

Interface Capabilities Overview

• Authentication: Kingdee Cloud uses application identity authentication. You need to configure AppId, AppSecret, account language, account ID, and other parameters in the Qeasy credential management, then obtain a login ticket via Kingdee.BOS.WebApi.ServicesStub.AuthService.ValidateUser before invoking business APIs.
• Request Structure: Core input parameters include FormId (here BD_Customer), FieldKeys (declare fields on demand), FilterString (incremental condition), Limit/StartRow (pagination parameters), and OrderString.
• Response Structure: Returns a JSON array where each element corresponds to one customer record. Base data fields are returned in the compound form "FieldName.FNumber" (e.g., FCreateOrgId_FNumber), and entry primary keys are returned as "EntryField_FEntryId".
• Pagination/Incremental Mode: Uses incremental pulling based on FApproveDate>='{{LAST_SYNC_TIME}}', combined with Limit+StartRow for pagination. A typical schedule runs every 30 minutes from 7:00 to 23:00.

Typical Field Mapping

How to Configure on Qeasy

In the Qeasy data integration platform, this interface is encapsulated as the "Kingdee Cloud Query Adapter," enabling visual configuration for quick onboarding:

1. Select Data Source: Choose "Kingdee Cloud" in the Data Source section and fill in the access URL, account information, and authentication credentials.
2. Choose API Template: Select "executeBillQuery-Customer Query" from the API template list; FormId will be auto-filled with BD_Customer.
3. Field Mapper: Qeasy's field mapper automatically reads the metadata and establishes mapping relationships between Kingdee fields (e.g., FCUSTID, FNumber, F_QKMS_JSTBM) and Jushuitan customer fields; you can also drag and drop for custom mapping.
4. Incremental Strategy: Enable incremental based on FApproveDate in the Scheduling Strategy and set the execution window (e.g., 5-59/30 7-23 * * *).
5. Target Configuration: Since this is a pure query strategy, choose "Write Empty Operation" for the Target, only persisting data and triggering downstream orchestration.

Cross-Solution Practical Points

1. Unify FNumber as the Business Primary Key: Although FCUSTID is the system primary key, the code is more stable for cross-system mapping, and Qeasy also recommends FNumber as the mapping key.
2. Always Pull F_QKMS_JSTBM: This is the mapping field Kingdee extended for Jushuitan; skipping it means losing "bidirectional positioning" capability.
3. Be Careful When Parsing Base Data Fields: Kingdee returns compound forms like "FieldName.FNumber". When mapping, remember to take the .FNumber suffix and don't pass the entire object as a string to the target system.
4. Don't Omit Multi-Organization Fields: FCreateOrgId and FUseOrgId are often different; pulling only one will cause missing records during cross-org usage.
5. Use FApproveDate Instead of FModifyDate for Incremental: Approval date is more stable and avoids jitter from draft-state changes.
6. Choose "Empty Operation" for Target: Don't write to the target system for a pure query strategy; it's more flexible to leave it to the orchestration layer to trigger downstream sync.

Pitfall Retrospective

• Direct String Concatenation in Filter Conditions Causes Errors: Kingdee requires ISO format with quotes; the safe approach is to use Qeasy's {{LAST_SYNC_TIME|datetime}} placeholder for auto-formatting.
• Excessively Large Limit Parameter Gets Truncated Server-Side: Kingdee has an upper limit for single returns; Qeasy adapter defaults to splitting at 2000 rows/page; do not manually override to 50000.
• Base Data Fields Mapped as Regular Strings: Passing FCreateOrgId_FNumber directly as a string results in downstream systems receiving JSON strings like "{Number:001,Name:Main Warehouse}". The correct approach is to extract only .FNumber in the field mapper.
• Wrong Incremental Field Causes Data Loss: One customer used FModifyDate for incremental, but draft-state changes triggered massive empty runs. Switching to FApproveDate immediately stabilized things.
• Empty Jushuitan Code Field Causes Downstream Matching Failure: F_QKMS_JSTBM is not maintained for some legacy customers; add a "skip when empty" fault-tolerant branch in the mapping.

When to Use

This interface is suitable for scenarios where Kingdee Cloud serves as the authoritative source for customer master data, requiring one-way sync of customer information to Jushuitan or middleware, and supporting base data mapping and business document mapping. If bidirectional writing or real-time event-driven sync is needed, consider using a change notification + document interface combination instead of high-frequency polling of this query interface.