What Problem Does This API Solve

In supply chain integration, product master data is the foundation of orders, inventory, and fulfillment. We frequently need to synchronize product records from the CRM to the WMS so that codes, prices, and minimum order quantities stay consistent on both sides. The OKKI CRM Product Query API serves exactly this purpose: it supports incremental pulls by update time, type filtering, and pagination. It is the source data entry for product master reconciliation and for downstream sync strategies such as order sync and inventory sync.

API Capability Overview

Authentication: Standard OKKI CRM API authentication using tenant credentials passed via request headers.
Endpoints: /v1/product/list returns a paginated product list. /v1/product/info retrieves a single product using product_no as the lookup key.
Request Structure: JSON-style request body or query parameters. Core parameters are start_index (page number), count (page size), start_time / end_time (incremental time window), removed (0 active / 1 deleted), and product_type (1 single / 2 multi-SKU / 3 bundle).
Response Structure: A list response where each record contains product_id, product_no, name, category, tax-inclusive cost, FOB price, minimum order quantity, and product type. Amount and quantity fields are typically returned as objects containing sub-fields such as amount and currency.
Pagination and Incremental Patterns: Pagination uses start_index + count with a default page size of 20. Incremental mode is driven by update-time windows. Across multiple customer projects, the scheduled task is commonly configured to run every 3 minutes during business hours (6:00–23:00).

Typical Field Mappings

Field	Type	Meaning	Practical Notes
product_id	string	Internal primary key of OKKI CRM	Treat as source-side unique identifier only; do not use for cross-system reconciliation
product_no	string	Business product code	Primary mapping key across systems; maps to the WMS goods_no
name	string	Display name of the product	Used for display and logs; avoid using it for code matching
group_id / group_name	string	Product category ID and name	Often used for downstream routing; names may collide
image	string	Product image URL	Keep the original URL when syncing to WMS; do not re-host
cost_with_tax	object	Tax-inclusive cost	Requires parsing of amount and currency sub-fields; normalize to base currency
fob	object	FOB price	Must convert across currencies for multi-currency projects
minimum_order_quantity	object	Minimum order quantity	Common pitfall: only the number is read, the unit is lost
product_type	string	1 single / 2 multi-SKU / 3 bundle	Bundle products must be expanded to child SKUs before downstream sync

Configuring on the Qeasy Platform

On the Qeasy Data Integration platform, this API is typically packaged as the "OKKI CRM Product Query" adapter under the source system connection. Configuration usually involves three steps. First, fill in the OKKI-side credentials on the adapter panel and test connectivity. Second, enable "paginated pull" and "incremental by update time" in the orchestration editor, mapping start_time to Qeasy's built-in "last sync time" cursor, and keep count between 20 and 100. Third, the field mapper automatically flattens response object-type fields (amount, quantity); engineers only need to align product_no with the downstream WMS goods_no on the mapping canvas. For bundle products, add a JS step in Qeasy's "data processing" node to expand the child specifications before writing downstream.

Cross-Scenario Practical Highlights

Persist the incremental cursor: Store start_time in Qeasy's "sync state" rather than in memory; otherwise restarts cause duplicate pulls or data loss.
product_no is the cross-system key: Do not use product_id for reconciliation; the OKKI primary key is unstable across systems, while the business code is the stable anchor.
Amount objects must be parsed: cost_with_tax, fob, and minimum_order_quantity are all objects. Reading them as plain strings loses currency and unit information.
product_type drives downstream routing: Types 1 and 2 are usually synced directly, while type 3 bundles must be expanded first; otherwise downstream stock will be inflated.
Handle deleted data separately: Records with removed=1 should go through a cleanup flow rather than the normal incremental stream, to avoid false alarms downstream.
Match schedule frequency with time windows: A 3-minute interval is common, but the gap between end_time and the next start_time should cover at least two cycles to prevent boundary data loss.

Pitfall Retrospective

Amount fields return nothing: Reading cost_with_tax directly as a string returns only the object reference. The safe approach is to enable "expand object" in Qeasy's field mapper, or add an expression to extract the inner value.
Bundle products not expanded: A product_type=3 product has a parent SKU and multiple child SKUs. Syncing it as a single record causes downstream inventory to multiply. This is a common trap; the safe approach is to expand by specification details in the data processing node before writing downstream.
Incremental boundary data loss: When end_time is set to "now" and the next round's start_time continues from there, records that span the boundary get lost. The safe approach is to rewind start_time by 1–2 minutes.
Multi-SKU products share the same name: Multiple SKUs share a single product_no and identical name, which causes downstream dedup to treat them as one record. The recommended approach on the WMS side is to use product_no + spec code as the unique key.
Silent failure on token expiry: When the OKKI token expires, the API may still respond but with empty content, misleading troubleshooting. The safe approach is to enable response non-empty validation and alerts in Qeasy.

When to Choose This API

Choose this API when you need to sync product master data from CRM to WMS or e-commerce backends, especially when incremental pulls by update time and type-based differentiation are required. If only a one-time full snapshot is needed, calling the list endpoint once is sufficient. For complex pricing strategies or tiered pricing, choose a dedicated quote API instead; this API does not cover those capabilities.

Field Manual and Cross-System Integration Tutorial for OKKI CRM Product Query API