What Problem Does This Interface Solve

In CRM–ERP bidirectional integration, product master data is the common foundation for orders, inventory, and pricing. The /v1/product/list interface of Xiaoman OKKICRM incrementally pulls product master data by update time, providing a unified product dictionary for item mapping, order synchronization, and quote calculation on the downstream side. Typical use cases include product master sync, category association, cost price retrieval, and FOB price retrieval — it is the upstream "data source switch" of the sales order integration chain.

Interface Capability Overview

Authentication: Xiaoman OKKICRM open-platform OAuth-style AccessToken, usually managed and refreshed by the connector on the downstream side.
Request Method: POST /v1/product/list, JSON body.
Filter Parameters: product_type (1=no SKU, 2=multi-SKU, 3=bundle), update_time_start / update_time_end (incremental window), page / page_size (pagination).
Response Structure: Typically { code, message, data: { items: [...], total } }, where each element in the list is a product object.
Pagination Mode: Classic page + page_size. On Qeasy, we recommend setting page_size to the platform's allowed maximum to minimize requests.
Incremental Mode: Window-based increment on update_time. The safe approach is [last_end - 1s, now], which avoids boundary misses.

Typical Field Mapping

Field	Type	Meaning	Practical Notes
product_id	string	Product primary key, unique within the system	On Qeasy's field mapper, usually mapped to downstream SKU primary key or custom external code
product_no	string	Product number / code	Cross-system business reference; recommended as dedup and idempotency key
name	string	Product name	Watch for leading/trailing whitespace — trim before display
group_id	string	Product category ID	Linked to `/v1/product/groups`; usually requires syncing categories first
group_name	string	Product category name	Redundant display field; do NOT use as a unique join key across systems
image	string	Product main image URL	Mind HTTPS and signed expiry; display side usually requires CDN transfer
cost_with_tax	object	Cost price including tax	Amount object — real scenarios require parsing `amount` and `currency`
fob	object	FOB price	Same structure as cost_with_tax; currency is easily confused
minimum_order_quantity	object	Minimum order quantity	Object type; parse and cast to int/double before writing downstream

How to Configure on Qeasy

On the Qeasy Data Integration Platform, Xiaoman's "Product Query" is typically encapsulated as a read-only source adapter: after app registration, the platform handles token refresh and rate limiting; the field mapper automatically projects product_id / product_no / name onto the downstream item model; the scheduler fires every 15 minutes via crontab: 15 7-22 * * *. The Target is configured as "write no-op", meaning this is a pure-query strategy and never writes back to Xiaoman. For incremental keys we recommend the platform's built-in "by update-time window" mode — Qeasy remembers the last boundary automatically.

Cross-Scenario Best Practices

Branch by product type first: product_type determines downstream SKU write logic. Always bucket by type before deciding whether to expand multi-SKU children.
Categories before products: Across multiple real projects, syncing /v1/product/groups first and then products significantly reduces dirty-data rate.
Always parse amount objects by sub-fields: cost_with_tax and fob are objects — always clarify currency and precision to avoid being overwritten by a default 0.
product_no is the stable anchor: product_id may change after some backend re-imports. The truly stable key is product_no — recommend using it as the unique external code on the downstream side.
Transfer images rather than direct linking: Xiaoman's image hosting often has signed URLs that expire; linking them directly will cause them to be judged invalid by the display layer.
Don't forget dedup on the incremental window: Multiple records may share the same update_time second — use product_id for idempotent upsert downstream.

Pitfall Recap

Pitfall 1: Using group_name as an ID. It is a redundant display field; once names change across systems, all originally-linked category chains break.
Pitfall 2: Treating amount objects as numeric and adding them directly. cost_with_tax is an object — direct + will error out or produce concatenated strings.
Pitfall 3: Setting page_size too large and triggering rate limits. Xiaoman enforces a single-response size limit — exceeding the allowed threshold causes truncation or rejection.
Pitfall 4: Incremental boundary misses. The incremental window does not cover update_time == last_end, causing boundary records to be dropped.
Pitfall 5: Token not auto-renewed. Early-morning tasks occasionally hit 401 — root cause is long-running jobs crossing the token validity window. Enable auto-refresh on Qeasy.

When to Use

Applicable to sales order pipelines where "Xiaoman OKKICRM is the product master source + downstream is a transactional system", requiring product dictionary sync, order-item mapping, and cost/price alignment. NOT applicable for reverse scenarios where downstream items must be written back to Xiaoman, for scenarios that only query order details without touching product master, or for financial reconciliation scenarios requiring real-time strict consistency rather than near-real-time sync.

Authoritative Field Handbook Tutorial: Xiaoman OKKICRM Product Query Interface