Authoritative Tutorial: OKKICRM Product Query API Field Handbook

What This API Solves

When bridging sales order flows between CRM and ERP, product master data is always the first step. The OKKICRM "Product Query" API pulls product records from the CRM side, providing field-level mapping and reconciliation for downstream Kintone material master data and sales order line items. It is the "upfront dictionary" of sales order integration; without it, subsequent order sync will easily suffer from inconsistent codes and missing amount fields.

API Capability Overview

• Endpoint: /v1/product/list, GET method, strategy type QUERY_ONLY (read-only, no writes to target).
• Authentication: OAuth-style access_token, consistent with other OKKICRM APIs; on Qeasy, it is usually managed and refreshed uniformly by the adapter.
• Response structure: returns a product list; each record contains basic info, category info, cost & price info, and order quantity info; product_id is the primary key, product_no is the code key.
• Pagination mode: classic page-based pagination with start_index (page number, default 1) + count (records per page, default 20), suitable for small-to-medium product catalogs.
• Incremental mode: pull by update time window via start_time / end_time, supporting YYYY-MM-DD or YYYY-MM-DD HH:MM:SS; typical schedule is every 20 minutes from 8:00–22:00.
• Filtering capability: product_type (1=no spec / 2=multi-spec / 3=combo), removed (default 0, set 1 to query deleted products) for traceability and reconciliation.
• Detail completion: when the list lacks full fields, call /v1/product/info with product_no as the info_key to fetch a single record's details.

Typical Field Mapping

How to Configure on Qeasy

On the Qeasy data integration platform, this API is typically invoked through the built-in OKKICRM adapter: after selecting the adapter at the data source, the platform automatically recognizes the request parameters and pagination structure of /v1/product/list, eliminating the need to hand-write paging logic.

• Metadata mapping: in the Qeasy field mapper, product_id is automatically bound as the id primary key, and product_no as the number code key, establishing a reconciliation relationship with the downstream Kintone material code.
• Incremental scheduling: the platform maintains a cursor using start_time / end_time; a typical strategy is a 20-minute interval, active from 8:00 to 22:00; off-hours are automatically skipped to save quota.
• Complex field handling: for object fields such as cost_with_tax, fob, and minimum_order_quantity, the platform auto-flattens via JSONPath. Common paths include $.amount, $.currency, which can be directly selected in the mapper.
• Detail completion: if list fields are incomplete, configure "on-demand info_api" in Qeasy, using product_no as the info_key to call /v1/product/info, enabling a list+detail two-stage pull.

Cross-Project Practical Points

1. Stable code over primary key: always use product_no for cross-system reconciliation; do not move product_id directly to Kintone — primary keys may be reused or drift across environments.
2. Sample object fields before mapping: do not rush to land cost_with_tax-like fields into the target table before actually parsing them. In multiple customer projects, we typically sample 3–5 real responses first to determine the flattening path.
3. Keep overlap on incremental windows: when pulling by update time, always push start_time 2–3 minutes earlier than the previous end time to avoid missing boundary data.
4. Test pagination upper bound: do not push count to the limit; in real scenarios, some tenants exhibit field truncation at count=100. The safe approach is to verify stability at 20–50 first, then scale up.
5. Two sides of deleted products: removed=1 is very useful for reconciliation, but production sync chains must explicitly filter them out — otherwise "ghost materials" appear downstream.
6. Category hierarchy requires a second mapping: OKKICRM's group_id does not map one-to-one to Kintone's material categories; add a mapping layer in Qeasy, otherwise orphan categories will appear.

Pitfall Recap

• Treating object fields as scalars: a client wrote cost_with_tax directly as float into Kintone, resulting in all downstream amounts being null. The lesson: objects must be flattened first with sub-field existence checks; the safe approach is a parsing script attached as a "pre-script" in the Qeasy mapper.
• Incremental start misalignment causes missed records: only advancing the cursor by end_time without pulling start_time back a few minutes caused updates near the boundary to be lost. The fix is to introduce the concept of an "overlap window".
• Multi-spec type filter reversed: confusing product_type=2 (multi-spec) with product_type=1 (no spec) caused wrong material profile types downstream. Add comments or an enum mapping table in the mapper.
• Misusing list primary key for info_api: calling /v1/product/info with product_id returns empty in some tenants. The safe approach is to strictly follow the official convention and use product_no as info_key.
• Image URL cross-domain / anti-hotlinking: after sync to downstream, images fail to render; common causes are CDN domain or referer misconfiguration. Always confirm whether the target side requires intermediate storage.

When to Use

Suitable for CRM→ERP product master data sync, sales order line item field mapping, material reconciliation, and price/cost information retrieval. The boundary: this API is read-only and does not write products into Kintone; if you need to land data, configure a separate Kintone material write strategy, chained via product_no.