What This Endpoint Solves

In digital projects across retail, trading, and manufacturing, we frequently need to synchronize customer master data from a CRM into an ERP for customer initialization, code reconciliation, and sales-stage alignment. The Xiaoman OKKICRM 'Query Customer' endpoint (/v1/company/list) is the starting point of this chain: it returns the full customer profile in one call — basic info, characteristic info, contact info, and management info — for field-level mapping with downstream systems such as Kingdee Cloud Cosmic.

Endpoint Capability Overview

Authentication: Standard Xiaoman Open Platform Access Token (carried in request headers). In Qeasy, this is typically wrapped in the adapter's authentication panel — just fill in your credentials.
Request Method: GET /v1/company/list, driven by query parameters.
Pagination: Traditional pagination based on start_index (page number, default 1) and count (page size, default 20). In Qeasy, the platform's pagination iterator automatically flips through pages until complete.
Incremental Mode: Pull incrementally via start_time / end_time against order_time (last update time). Qeasy's field mapper natively supports variables such as {{LAST_SYNC_TIME|datetime}} and {{CURRENT_TIME|datetime}}.
Filtering Capabilities: removed (include deleted), all (public sea + private sea vs. private sea only), group_id (customer group).
Response Structure: Array-shaped; each record returns six field groups flatly — identifiers, time, basic info, characteristic info, contact info, and management info.

Typical Field Mappings

Field Name	Type	Meaning	Practical Notes
company_id	string	Unique customer identifier in the source system, primary key	Specified as `id` in metadata; the anchor for cross-system reconciliation
name	string	Full company name	Specified as `number` in metadata; can be matched against Kingdee name or code
short_name	string	Company short name	Used for daily display; may share its source with `基本信息简称`
serial_id	string	Company code / customer code	Frequently used as the mapping key to Kingdee's customer code
order_time	string	Last update time	The baseline for incremental synchronization
create_time	string	Record creation time	Used for full initialization sync
基本信息公司名称	string	Full company name in the basic-info module	May duplicate `name`; verify before mapping
基本信息简称	string	Short name in the basic-info module	Same-source risk with `short_name`; avoid double-write
基本信息客户来源	string	Lead acquisition channel	Custom dictionary; verify enum on the target side before landing
特征信息客户类型	string	Customer classification	Same as above; value mapping usually required
特征信息国家地区	string	Country or region	Mind Chinese/English differences in cross-region scenarios
特征信息省份	string	Province	Combined with country for address classification
联系信息详细地址	string	Detailed contact address	Consider address cleansing before writing to the target
管理信息客户阶段	string	Sales stage / lifecycle	The field with the largest dictionary gap; always build a mapping table

How to Configure in Qeasy

In the Qeasy Data Integration Platform, Xiaoman OKKICRM is packaged as a ready-to-use adapter. The configuration flow looks like this: create a new integration flow → choose "Xiaoman OKKICRM" as the source → select the "Query Customer" action template → in the Request Parameters panel, tick start_index, count, start_time, end_time, group_id, removed, all as needed. The platform's pagination iterator automatically handles paging; the field mapper recognizes company_id as the primary key and name as the code field, which can be dragged directly onto target-side columns. For incremental scenarios, simply reference the {{LAST_SYNC_TIME|datetime}} variable in time parameters, and you get a stable incremental sync running every 5–10 minutes.

Cross-Project Practical Points

Separate primary key from code: company_id is the system primary key used for cross-system reconciliation; serial_id is the business code used to land in Kingdee's customer code. Do not mix them.
Always include order_time for incremental sync: order_time is the most reliable basis; do not use create_time, or newly created-and-modified customers will be missed.
Public sea vs. private sea depends on the business: Cross-enterprise sync usually uses all=1 to pull everything; individual sales-performance scenarios use all=0 to pull the private sea only.
Pick one of the duplicate fields: name vs. 基本信息公司名称, and short_name vs. 基本信息简称 — pick only one to avoid duplicate-value unique-constraint violations on the target side.
Combine address with province/city: 特征信息省份 + 联系信息详细地址 should be mapped together; otherwise the target's province/city breakdown will be incomplete.
Always build a mapping table for customer stage: The sales-stage dictionaries in Xiaoman and Kingdee differ; without a value mapping table you will end up with dirty data like "Won" turning into "Lead".

Pitfall Retrospective

Pitfall 1: Incremental data loss. Using create_time directly for incremental sync causes modified customers to never update. The safe approach is to use order_time steadily and set start_time to the last sync time.
Pitfall 2: Duplicate-field double-write. Mapping both name and 基本信息公司名称 to Kingdee's customer name triggers a name-mismatch warning. The recommended approach is to add a de-duplication rule in Qeasy's field mapper and keep only one.
Pitfall 3: Pagination overrun. No count cap set, pulling tens of thousands of records at once blows up memory. The safe approach is to set count=100 explicitly and pair it with the pagination iterator.
Pitfall 4: Deleted customers flowing back in. With removed defaulting to 0, a single careless change to 1 resyncs deleted customers. The safe approach is to hardcode removed=0 in the request parameters and not let business users modify it.
Pitfall 5: Customer-stage dictionary mismatch. Without a value mapping table, "Won" gets written into Kingdee's "Prospect" category. The safe approach is to build a stage mapping table in Qeasy first, then land the data.

When to Use This Endpoint

Whenever the business involves synchronizing CRM customer master data to an ERP, or performing incremental reconciliation by update time, this endpoint is the first choice; however, it only "pulls" — it does not "write". If you need to land the data into downstream systems such as Kingdee or Cloud Cosmic, it must be paired with subsequent write strategies, and synchronization of deleted customers requires careful evaluation of business necessity.

Authoritative Field Guide for the Xiaoman OKKICRM 'Query Customer' API: From Pull to Use, All in One Place