What This Interface Solves

In supply chain integration, customer master data is the foundation for all downstream documents such as sales orders, outbound shipments, and return orders. When we treat Kingdee Cloud as the ERP source of truth and need to sync customer records to e-commerce frontends, OA approval systems, or other business systems, the very first interface to open up is the "Query Kingdee Customer" endpoint. This interface uses Kingdee Cloud's executeBillQuery capability to batch fetch customer records by primary key, code, name, organization, external code, and other conditions, providing the reference data for cross-system customer code mapping and document matching.

Interface Capability Overview

Source System: Kingdee Cloud (Kingdee.Cloud)
Business Object Form: BD_Customer (Master Data - Customer)
API: executeBillQuery, method POST, effect QUERY
Authentication: Standard Kingdee Cloud user/tenant authentication; in on-premise deployments, an internal network access channel is required
Request Structure: Form ID FormId + field set FieldKeys + filter condition FilterString + pagination parameters Limit/StartRow/TopRowCount
Response Structure: JSON array, each row is one customer record, field order matches FieldKeys; when autoFillResponse: true, response fields are auto-populated
Pagination Mode: Limit (page size, typically 2000) + StartRow (starting row index), cursor-style pagination
Incremental Mode: Filter by approval time in FilterString, e.g. FApproveDate>='{{LAST_SYNC_TIME|datetime}}', combined with idCheck: false in metadata for on-demand fetching
Scheduling: Across multiple customer scenarios, common cadences are "every 5 minutes (07:00–23:59)" or "every 8 minutes (07:00–23:59)", typically paused during off-hours

Typical Field Mapping

Field Name	Chinese Name	Type	Business Meaning	Practical Notes
FCUSTID	Entity Primary Key	string	Unique customer identifier within Kingdee, used for cross-system association and deduplication	Internal ID; not recommended as a mapping key across systems; prefer `FNumber` or `F_352_waibuma`
FNumber	Code	string	Customer business code, the main identifier used within and across systems	Defined as `number` in metadata; preferred key for cross-system mapping
FName	Name	string	Customer full name, used for display and manual verification	Names may collide; always combine with code for matching
FCreateOrgId_FNumber	Create Org	string	Code of the organization that created the customer	Identifies data ownership in multi-org scenarios
FUseOrgId_FNumber	Use Org	string	Code of the organization that uses the customer; the owning org in multi-org setups	Required; `FilterString` often filters by this field
FDescription	Description	string	Customer description or remark	Limited length; do not store sensitive information
FCustTypeId_FNumber	Customer Type	string	Customer category code (retail/wholesale/enterprise, etc.)	Reference field pointing to the customer type master data
FGroup_FNumber	Customer Group	string	Customer group code	Used to categorize by region, channel, etc.
FSALDEPTID_FNumber	Sales Dept	string	Code of the sales department responsible for the customer	Commonly used for performance and ownership
FSELLER_FNumber	Salesperson	string	Code of the salesperson responsible for the customer	Customer ownership and performance review
FSETTLETYPEID_FNumber	Settlement Type	string	Settlement type code (cash/monthly/prepayment, etc.)	Affects downstream collection flow
FRECCONDITIONID_FNumber	Receipt Condition	string	Receipt condition code	Linked with credit limit and payment terms
FShortName	Short Name	string	Customer short name	Used in documents and reports with limited space
FADDRESS	Address	string	Contact address	Needed for logistics and invoicing
FTEL	Phone	string	Contact phone	Updates frequently; validate separately
FFAX	Fax	string	Fax number	Mainly legacy customers; often empty for new ones
FCompanyClassify_FNumber	Company Class	string	Company classification code (general taxpayer/small-scale taxpayer, etc.)	Directly affects invoicing rules
FINVOICETITLE	Invoice Title	string	Invoice title for billing	Strongly bound to tax information
FINVOICEBANKACCOUNT	Bank Account	string	Bank account for invoicing	Sensitive field; mask in transit and storage
FCURRENCYID_FNumber	Currency	string	Default transaction currency code	Required in multi-currency scenarios
FTRADINGCURRID	Settlement Currency	string	Settlement currency identifier	May differ from transaction currency
F_352_waibuma	External Code	string	External system code, used to map with customer codes in Guanyi or other systems	Key mapping field for cross-system integration; the `F_352_` prefix indicates a custom extension field

How to Configure on Qeasy

In the Qeasy Data Integration platform, the Kingdee Cloud customer query is typically wrapped as a query action under the "Kingdee Adapter". The configuration flow is:

Data Source Selection: In "Data Source", pick "Kingdee Cloud", and enter the on-premise access address and tenant information; the adapter already encapsulates executeBillQuery authentication and request assembly.
Interface Action Configuration: When creating a strategy, select the "Query Kingdee Customer" template. FormId is automatically filled with BD_Customer, and FieldKeys defaults to all 22 core fields. FilterString can use a time variable (LAST_SYNC_TIME) for incremental conditions.
Field Mapper: Qeasy's field mapper automatically maps Kingdee fields like FNumber, FName, and F_352_waibuma to the target system (Guanyi Cloud, Weaver OA, etc.) customer code, customer name, and external code. After mapping, sample-check the primary keys and names in "Preview" before enabling the schedule.

If the Target is configured as a "write empty operation", the strategy is a pure query strategy—it pulls data but does not write anywhere, often serving as the master data baseline for downstream sync strategies.

Cross-Scenario Best Practices

From multiple real-world integration projects (Guanyi Cloud supply chain integration, Weaver OA-E9 integration, etc.), we distilled the following common lessons:

Use FNumber as the cross-system primary mapping key: FCUSTID is not suitable as a direct mapping key across systems; FNumber is stable both within and across systems.
F_352_waibuma is the key field for cross-system integration: Its value is usually maintained as the external system's customer code (e.g., Guanyi Cloud); prefer it for document matching.
Always filter by FUseOrgId_FNumber in multi-org scenarios: Otherwise, customers from other organizations will be pulled in, causing mapping chaos.
Use FApproveDate instead of FModifyDate for incremental sync: Approval time is more stable and avoids syncing intermediate-state data.
Fields with _FNumber suffix are reference fields: The response returns the code, not the primary key ID; downstream systems must resolve the code against master data.
Tighten the schedule window by business period: 07:00–23:00 is common; pausing during off-hours saves resources and reduces pressure on the tenant.

Pitfall Recap

Pitfall 1: Using FCUSTID as the cross-system primary key In one retail scenario, the team stored Kingdee's FCUSTID directly into Guanyi Cloud's customer relation field. Once Kingdee rebuilt or migrated primary keys, all external associations broke. The safe approach is bidirectional mapping with FNumber as primary and F_352_waibuma as auxiliary.
Pitfall 2: Not filtering by use org, pulling customers from the entire group In a multi-org setup, customers from one sales organization should not be synced to others. Without filtering, a single query can return hundreds of thousands of customer records and trigger rate limits. The safe approach is to add FUseOrgId.FNumber='specific org code' in FilterString.
Pitfall 3: Wrong incremental field causing missing or duplicate data Some strategies used FModifyDate for incremental sync, but customers under approval have their FModifyDate rewritten repeatedly, causing the same customer to be synced multiple times. The safe approach is to use FApproveDate combined with idCheck: false so the system fetches as needed.
Pitfall 4: Treating _FNumber fields as primary key IDs Engineers sometimes see a numeric value in FSELLER_FNumber and assume it's the employee ID, but it's actually the employee code. Downstream reverse lookup should match the code against master data, not treat it as an ID.
Pitfall 5: Unmaintained F_352_waibuma causing master data mismatches External codes depend on manual maintenance in Kingdee; some legacy customers have missing values, so downstream systems can't find the corresponding customer. The safe approach is to add an "External Code Missing Report" and clean up regularly.

When to Use

This interface is the "standard" for customer master data in supply chain integration. Whenever there is a need to sync customer records between Kingdee Cloud and any business system, or to map customer fields on documents, prefer BD_Customer + executeBillQuery. It is not suitable when only document-level customer matching is needed (use the customer field on the document interface directly), or when Kingdee Cloud is not the customer data source.

Kingdee Cloud Customer Query API Field Manual: executeBillQuery Practical Tutorial