Authoritative Tutorial on the Xiaoman OKKICRM "Query Products" Interface Field Handbook

What Problem Does This Interface Solve

"Query Products" is the product master data query interface exposed by Xiaoman OKKICRM. Its typical use is to synchronize product archives from the CRM side to downstream ERPs (Digiwin T100, Kingdee Cloud Cosmic/Star, etc.), achieving unification of product codes, categories, costs, prices, and minimum order quantities. In CRM-ERP integration, this interface is almost always the first step, and its stability directly determines whether subsequent order and quotation links can run smoothly.

Interface Capability Overview

• Endpoint: /v1/product/list, GET method; detail endpoint /v1/product/info.
• Authentication: Standard AccessToken authorization of Xiaoman OKKICRM, carried in the header.
• Request Structure: Supports pagination (start_index default 1, count default 20), incremental time window (start_time, end_time, format yyyy-MM-dd or yyyy-MM-dd HH:mm:ss), product type filtering (product_type: 1 no spec / 2 multi-spec / 3 combo), and whether to include deleted data (removed: 0 no / 1 yes).
• Response Structure: JSON array, each record corresponds to one product, with embedded structured fields such as cost, price, and minimum order quantity.
• Incremental Mode: Strictly pulls by update time window. In production, the sliding window from {{LAST_SYNC_TIME}} to {{CURRENT_TIME}} is commonly used.
• Strategy Type: QUERY_ONLY, pure query. Target is configured as "write empty operation", data lands in QeasyCloud's staging area for downstream strategies to consume.

Typical Field Mapping

How to Configure on QeasyCloud

In the QeasyCloud data integration platform, "Query Products" has been encapsulated as an out-of-the-box adapter. The specific approach is:

1. When creating a new strategy, select the "Xiaoman OKKICRM-Query Products" source system template, and select "Write Empty Operation" for Target.
2. In QeasyCloud's field mapper, product_no is automatically used as the primary key (id), and name as the code (number), no need to manually modify metadata.
3. The incremental parameters bind to system variables {{LAST_SYNC_TIME}} and {{CURRENT_TIME}}, and the platform automatically maintains the time cursor.
4. If you need to call the detail interface to supplement fields, configure info_api=/v1/product/info and info_key=product_no in "otherRequest", and the platform will batch query back by primary key.
5. Downstream consumers (Kingdee/Digiwin write strategies) can directly reference the output dataset of this strategy without re-connecting to Xiaoman API.

Cross-Solution Practical Points

1. Recognize product_no as the primary key, not product_id: product_id is the ID within the Xiaoman system and cannot match across systems; product_no is the business code and must be used when mapping with ERP material codes.
2. Object type fields must be decomposed: Fields like cost, price, and minimum order quantity are returned as objects by the API, and you won't get the value if you use them directly as strings. In QeasyCloud's field mapper, you can use expressions to take the value sub-field.
3. Don't set the incremental window too wide: In production, it is recommended that a single window not exceed 24 hours to avoid timeouts or missed data; a scheduled pull every morning is more stable than real-time polling.
4. Deleted data should be handled separately: removed=1 queries soft-deleted records, which are usually ignored in master data synchronization, but the quantity should be monitored. An abnormal surge indicates upstream misoperation.
5. Pay attention to product_type for multi-spec/combo products: The structures of no-spec (1), multi-spec (2), and combo (3) products differ greatly, and must be processed separately when mapping to ERP material structures, not with a one-size-fits-all approach.
6. Custom fields are read by field ID: For custom fields like "Belonging Company", the field name is a numeric ID (such as 41371572553362). When mapping, read directly by field ID; don't try to find the Chinese name.

Pitfall Review

1. Pitfall One: Using product_id as the primary key for cross-system mapping. The consequence is that the same product cannot match across different systems, and the data is all messed up. The safe approach is to uniformly use product_no and bind it directly as id in QeasyCloud.
2. Pitfall Two: Getting null when taking the value of the cost field. The reason is that it returns an object rather than a pure value. The safe approach is to write an expression in the field mapper to take cost.value or cost_with_tax.value.
3. Pitfall Three: Missing data in incremental pulls. The reason is that start_time uses the local time zone but Xiaoman returns UTC, and the boundary value is exactly offset. The safe approach is to uniformly use UTC time variables in QeasyCloud, or to add an hour of redundant window on the edge.
4. Pitfall Four: Multi-spec products become multiple materials after being synced to the ERP. The reason is that product_type was not distinguished, and all products were treated as no-spec. The safe approach is to first route by product_type, and expand multi-spec products in the downstream ERP.
5. Pitfall Five: The number of calls to the detail interface explodes. The reason is that not all fields were obtained in the list interface, and the detail is called for each record. The safe approach is to first confirm whether the list interface fields are sufficient. If not, go to /v1/product/info, and configure concurrency rate limiting in QeasyCloud.

When to Use

"Query Products" is suitable for scenarios where Xiaoman CRM's product master data needs to be synchronized to downstream ERPs (Digiwin, Kingdee, etc.), or for building a unified product center data middle platform. It is a pure query strategy and does not directly write to the target system, usually as the "first step pull" of the entire product master data synchronization chain. If your scenario is to write products from ERP to CRM, you should go to the write interface on the Digiwin/Kingdee side instead of this one.