What Problem Does This Interface Solve

In supply-chain integration between JikeCloud and Kingdee Cloud Skylight, customer master data is the foundation for orders, receivables, and invoicing. This interface calls the Kingdee executeBillQuery WebAPI to paginate through the BD_Customer form in batch. Typical use cases include syncing JikeCloud channels/customers with Kingdee customer profiles, cross-system customer code mapping, and propagating sales org and salesperson ownership so downstream modules have a solid master-data base.

Interface Capability Overview

Authentication: Kingdee Cloud Skylight WebAPI third-party / integration login. On the Qeasy Cloud adapter you configure data center, user, secret, and App ID.
Request method: POST to executeBillQuery with fixed FormId = BD_Customer.
Request parameters: Limit (default 2000), StartRow (starts at 0), TopRowCount (optional, returns total row count), FilterString (filter conditions), FieldKeys (field list, e.g. FCUSTID,FNUMBER,FNAME,...).
Response structure: a two-dimensional rowset, one customer profile per row. In metadata, id is FCUSTID, number is FNumber.
Pagination / incremental mode: typical pattern is FApproveDate >= '{{LAST_SYNC_TIME|dateTime}}' for incremental, then paginate with StartRow/Limit and advance StartRow += Limit until the returned rows are fewer than Limit.
Strategy type: QUERY_ONLY with target configured as "write null operation"; the strategy only pulls data, leaving persistence and reconciliation to downstream strategies.

Typical Field Mapping

Field Name	Type	Meaning	Practical Notes
FCUSTID	string	Customer primary key ID, Kingdee internal unique identifier	Prefer as idempotency key for cross-system reconciliation; Qeasy's field mapper automatically treats it as the primary key.
FNumber	string	Customer business code	Primary/foreign key when mapping to JikeCloud channel codes; keep encoding rules consistent.
FName	string	Customer full name / company name	Used for display and reconciliation; customers with the same name are distinguished by FNumber.
FShortName	string	Customer short name	Display field in lists and search boxes.
FCreateOrgId_FNumber / FUseOrgId_FNumber	string	Creating / using organization code	Required for multi-org customers; prefer FUseOrgId for org-isolated filtering.
FCustTypeId_FNumber / FGroup_FNumber	string	Customer category, group code	Drives customer tiering and pricing strategy routing.
FSALDEPTID_FNumber / FSELLER_FNumber	string	Sales department, salesperson code	Source of performance attribution and default values on sales orders.
FSETTLETYPEID_FNumber / FRECCONDITIONID_FNumber	string	Settlement method, receivables term code	Affects AR aging and credit checks.
FDISCOUNTLISTID_FNumber / FPRICELISTID_FNumber	string	Discount list, price list code	Both list and customer must have an effective version; otherwise no price is returned.
FTaxType_FNumber / FCompanyClassify_FNumber	string	Tax category, company classification code	Drives invoicing and tax compliance validation.
FADDRESS / FTEL / FFAX / FZIP / FWEBSITE	string	Address, phone, fax, zip, website	Baseline fields for logistics and reconciliation.
FINVOICETITLE / FTAXREGISTERCODE	string	Invoice title, tax registration number	Key pre-invoicing validation fields; Qeasy validates non-empty per required rules.
FINVOICEBANKNAME / FINVOICETEL / FINVOICEBANKACCOUNT / FINVOICEADDRESS	string	Invoice bank info	Separate from the receiving-bank set below; one customer can have multiple accounts.
FSUPPLIERID_FNumber / FGROUPCUSTID_FNumber	string	Linked supplier, group customer code	Required for supplier-customer unification and group customer scenarios.
FBankTypeRec_FNumber / FBankDetail_FNumber / FTextBankDetail / FOpenAddressRec / FCNAPS	string	Receiving bank, branch, address, CNAPS	CNAPS directly impacts payment success; always take the latest value from Kingdee.
FBANKCODE / FACCOUNTNAME / FISDEFAULT1	string	Bank account, account name, default-account flag	In multi-account scenarios, use FISDEFAULT1 to identify the default account.
FCURRENCYID_FNumber	string	Default transaction currency code	For multi-currency customers, fetch the price list per currency.
FDefaultConsiLoc_FNumber / FDefaultSettleLoc_FNumber / FDefaultPayerLoc_FNumber / FDefaultContact_FNumber	string	Default consignee / settle / payer location, default contact code	Basis for auto-filling defaults on orders.
FMarginLevel	string	Margin level (%)	Used in credit / margin control scenarios.

How to Configure on Qeasy Cloud

On the Qeasy Cloud Data Integration Platform, Kingdee Cloud Skylight is typically encapsulated as an "adapter + metadata" pair: the adapter handles executeBillQuery authentication, URL composition, and pagination iteration; the source metadata source-metedata/金蝶客户查询_source.json describes the BD_Customer field set with primary keys (id=FCUSTID, number=FNumber). Target metadata is set to "write null operation" and the strategy type is QUERY_ONLY.

In the field-mapping phase, Qeasy's field mapper automatically loads all source fields. You can directly map FCUSTID to the target's customer_id and FNumber to customer_code, while _FNumber-suffixed reference fields (organization, customer category, salesperson, etc.) are usually mapped to code fields on the target side; Qeasy resolves names on demand at runtime. The scheduled task can follow the customer's business rhythm, e.g. 3-59/20 7-22 * * * (every 20 minutes, 07:00–22:00).

Cross-Scenario Practical Points

Use FCUSTID as the primary key, FNumber for cross-system mapping: Kingdee's internal primary key is stable, but FNumber is the business code used to map with JikeCloud channel codes.
Always include FUseOrgId and FApproveDate in the filter: multi-org customers must be narrowed down by using organization first, otherwise you pull all group customers; the incremental depends on approve date, since unapproved customers should not propagate even if the profile exists.
Paginate via StartRow/Limit, do not use TopRowCount as termination: TopRowCount is the total row count and may cause the loop to end early; the safe pattern is to keep looping until returned rows < Limit.
Reference fields always come as _FNumber-suffixed codes: organization, customer category, salesperson, price list, etc., are all reference fields; Qeasy receives codes and names must be resolved on the target side or maintained in lookup tables.
Invoice info and receiving bank are two independent field sets: invoicing uses the FINVOICE* series, receiving uses the FBANK*/FACCOUNTNAME series—never mix them when building invoicing or payout interfaces.
Price list and discount list must be effective for the customer: FDISCOUNTLISTID_FNumber and FPRICELISTID_FNumber give codes, but order placement validates the version and effective period; add a customer profile integrity check on the Qeasy side.

Pitfall Recap

Pitfall 1: malformed FilterString returns an empty page. Kingdee filter syntax is strict, e.g. FUseOrgId.FNumber = '100' and FApproveDate>='2024-01-01 00:00:00'; strings must be wrapped in single quotes and dates must be fully written.
Pitfall 2: wrong field chosen for incremental cursor. Using FModifyDate will also capture unapproved changes, propagating invalid changes downstream; FApproveDate is safer.
Pitfall 3: default account is not unique. With multiple bank accounts under one customer, FISDEFAULT1='1' may not be unique; Qeasy must dedupe by (customer code + default flag) to avoid persistence conflicts.
Pitfall 4: supplier-customer unification overwrites supplier data. When FSUPPLIERID_FNumber links to the supplier profile, the target system may also maintain the supplier and get overwritten; before writing, check whether FCustTypeId includes the "supplier-customer" flag.
Pitfall 5: FieldKeys missing FCUSTID. Some scenarios only take business fields and miss the primary key, causing duplicates on the target side because no key is found; Qeasy's field mapper keeps the primary key by default—don't remove it manually.

When to Use

Use this interface when you need to sync Kingdee Cloud Skylight customer master data (profiles, categories, org ownership, invoicing and bank info) into JikeCloud, e-commerce mid-platforms, or downstream ERP/CRM. It is NOT for writing, deleting, or auditing customer profiles; those require save / submit / audit write interfaces.

Authoritative Tutorial on Kingdee Cloud Skylight Customer Query Interface Field Handbook (executeBillQuery / BD_Customer)