Authoritative Tutorial on the Kingdee Cloud Customer Contact Query API Field Manual

What Problem This API Solves

In retail, wholesale, and service industries, customer contacts are scattered across CRM systems (e.g., Xiaoman OKKICRM) and ERP systems (Kingdee Cloud). We need a unified "contact archive" on both sides: pull contact master data from Kingdee incrementally into the CRM, or vice versa to reconcile contacts between CRM and ERP. This API is purpose-built for that scenario. It uses Kingdee's executeBillQuery WebAPI to fetch BD_CommonContact (Common Contact) master data in pages, filtered incrementally by approval date, providing a data foundation for subsequent sync, reconciliation, and relationship maintenance.

API Capability Overview

• System: Kingdee Cloud (Kingdee.Cloud), master data domain.
• Endpoint: executeBillQuery WebAPI (POST).
• Form ID: BD_CommonContact (Common Contact).
• Request parameters: Limit (page size), StartRow (start row), TopRowCount (total row count, default 0), FilterString (filter condition), FieldKeys (returned field set), FormId (fixed as BD_CommonContact).
• Response structure: Kingdee standard ListView containing rows whose columns are defined by FieldKeys.
• Pagination: classic StartRow + Limit pagination, driven by {{PAGINATION_START_ROW}} and {{PAGINATION_PAGE_SIZE}} placeholders.
• Incremental mode: default filter FApproveDate >= '{{LAST_SYNC_TIME|dateTime}}', scheduled every 10 minutes during working hours 08:00–20:00.
• Strategy type: QUERY_ONLY, Target side is a "null write operation", pure query.

Typical Field Mapping

How to Configure on Qeasy

On the Qeasy Data Integration Platform, this API is wrapped as a "Query Strategy" template within the Kingdee Cloud adapter. Configuration typically follows these steps:

1. Select source: Kingdee Cloud, pick the executeBillQuery adapter.
2. Set FormId: BD_CommonContact; the platform prefills the default field set.
3. Choose FieldKeys: in Qeasy's field mapper, tick the fields you need; the platform automatically assembles them into the FieldKeys request body.
4. Configure FilterString: the default template already includes FApproveDate incremental filtering; replace it with the platform's {{LAST_SYNC_TIME|dateTime}} placeholder.
5. Set pagination: bind StartRow and Limit to {{PAGINATION_START_ROW}} and {{PAGINATION_PAGE_SIZE}} respectively; the Qeasy scheduler auto-paginates until an empty result is returned.
6. Target side: select "null write operation"; this strategy only produces a data snapshot, no real target write.
7. Scheduling: crontab */10 8-20 * * *, pulls every 10 minutes during working hours.

Cross-Solution Practical Tips

1. Use FNumber as the anchor for cross-system reconciliation: FCUSTID is Kingdee's internal primary key and may break after migration; FNumber as a business code is more stable.
2. Prefer approval date over modification date for incremental filtering: FApproveDate better reflects business-effective state than FModifyDate, avoiding "draft-state" contacts.
3. Always carry UseOrgId in multi-org scenarios: different using orgs see different contact lists; omitting it leads to missing data.
4. Pull both code and name for FGroup: code is stable but not human-readable; name is readable but mutable; combining both gives stability and debuggability.
5. Don't be greedy on page size: oversized pages often time out in Kingdee WebAPI; PageSize around 500–1000 is safer in real projects.
6. Don't accidentally turn null-write into a real target: this strategy is a "query snapshot"; attaching a real target write causes duplicate landings.

Pitfall Recap

1. FilterString time format issue: Kingdee expects yyyy-MM-dd HH:mm:ss; UTC or timezone-bearing ISO strings return empty results. The safe approach is to use the Qeasy variable {{LAST_SYNC_TIME|dateTime}} which is uniformly formatted by the platform.
2. Related customer filter confusion: contacts have no direct "customer code" field; FCustTypeId, FGroup, etc., come through relationships. To filter contacts under a specific customer, use a FCUSTID IN (...) subquery in FilterString rather than a direct FCUST='xxx'.
3. Pagination infinite loop: when StartRow is out of range, some Kingdee versions return empty while others return errors. Qeasy auto-detects termination via row count, but if a custom script treats empty results as exceptions, it falls into a loop.
4. FIsTrade type drift: across Kingdee versions we have seen true/false, 1/0, True/False; the integration layer must normalize.
5. FName encoding in multilingual environments: when the customer switches to Traditional Chinese or English, FName may contain emoji or fullwidth characters; CRM ingestion must validate UTF-8 to avoid mojibake.

When to Use It

Best suited for unidirectional pull, reconciliation, or mirroring of customer contacts between CRM and Kingdee Cloud — scenarios such as CRM contact archive enrichment, ERP contact change notifications, and contact–customer relationship rebuilding. Not suitable for writing contacts back into Kingdee, bidirectional real-time sync (which requires a paired write strategy), or contact integration with non-Kingdee ERP systems.