What This API Solves

The Xiaoman OKKICRM /v1/invoices/order/list API is used to batch-pull sales order master data and line item details based on time windows and multi-condition filters. Across multiple customer projects we have worked on, the typical use case is synchronizing sales orders from the CRM side to an ERP (such as Jikeyun), achieving unified reconciliation of order status, amounts, customers, and product details. The API supports incremental queries, status filtering, and detail completion, making it one of the most common entry points in the sales order domain.

API Capability Overview

Authentication: Uses Xiaoman OKKICRM's standard Access Token authentication. The request header carries Authorization: Bearer {token}, which must be obtained in advance via the authorization API and refreshed periodically.
Request Structure: POST /v1/invoices/order/list with form/JSON body. Core parameters include start_time, end_time, start_index (page number, default 1), count (per page, default 10), status (status filter, half-width comma separated), approval (0/1), and removed (0/1).
Response Structure: Returns a JSON object with core fields data (order array), total (total record count), and total_page (total pages). Each order record contains order master information and the product_list line items.
Pagination and Incremental Mode: A dual-layer incremental mechanism based on start_time/end_time plus page number start_index. In multiple customer projects, the safe approach is to bind start_time to {{LAST_SYNC_TIME}}, take end_time as the current time, and run every 5 minutes (crontab: */5 7-22 * * *), ensuring timeliness without missing records.
Detail Completion: When the list API returns an empty or incomplete product_list, the detail API /v1/invoices/order/info can be called with order_id as the primary key (info_key) to fetch complete data.

Typical Field Mapping

Field Name	Type	Meaning	Practical Notes
order_id	string	Order primary key, unique within Xiaoman	Used as the detail API primary key parameter; always validate for null
order_no	string	Order business code	Used for cross-system order deduplication and reconciliation
name	string	Order name	Used for document display, may contain Chinese characters and symbols
amount	float	Total order amount	Mind currency and exchange rate conversion
addition_cost_amount	float	Total additional cost	Shipping, taxes; excludes product amounts
product_total_amount	float	Total product amount	Difference from `amount` equals additional cost
product_total_count	float	Total product quantity	Used for order scale judgment
company_name	string	Customer company name	Flattened field, preferred
company_phone	string	Customer phone	Flattened field preferred
company_address	string	Customer address	May duplicate with `company` object
customer_name	string	Contact name	Distinct from company name
customer_phone	string	Contact phone	Distinct from company phone
customer_email	string	Contact email	May be empty, handle nulls
transport_mode	string	Shipping method	Used for logistics linkage
account_date	datetime	Order closing date	Used for order lifecycle analysis
product_list	array	Order line items	May be empty in list API, requires detail completion
users_info	object	Performance owner	Basis for sales performance statistics
handler_info	object	Order handler	Used for CRM ownership determination
status_info	object	Order status	Contains status code and name
exchange_rate	string	Exchange rate	Required in multi-currency scenarios

How to Configure on Qeasy

In the Qeasy data integration platform, this API is typically encapsulated as a "Query Adapter". We have configured it for multiple customer projects and summarized three key experiences:

Adapter Registration: Select Xiaoman OKKICRM as the "Source System" in Qeasy, fill in /v1/invoices/order/list as the entry path, and configure token authentication and refresh strategy. Qeasy's authentication manager automatically handles token expiration retries.
Field Mapper: The platform field mapper automatically maps core fields such as order_id, order_no, and amount to Qeasy's unified concept model (e.g., order_id, order_no, order_amount). Downstream target systems (Jikeyun) can reference them directly without redefining fields.
Incremental Strategy: Configure the crontab as */5 7-22 * * * in Qeasy's "Scheduling Strategy", bind start_time to Qeasy's {{LAST_SYNC_TIME}} variable, and take end_time as {{CURRENT_TIME}}. The platform persists the last sync timestamp, enabling breakpoint resumption without manual intervention.

In addition, when product_list is empty, you can configure detail completion rules in Qeasy's "Data Processing" node to automatically call /v1/invoices/order/info with order_id to fill in line items, avoiding downstream data loss.

Cross-Solution Practical Points

From multiple customer projects we have delivered, the following six common experiences are worth highlighting:

Keep the incremental time window conservative: start_time should be 1-2 minutes earlier than end_time to avoid missing orders due to server clock drift; end_time must not be a future time, or some orders will be excluded.
Balance pagination limit and performance: count is recommended to be 50-100, which improves single-pull efficiency without triggering rate limits; when total pages exceed 50, concurrent sharding must be implemented.
List and detail APIs work together: The list API's product_list is often empty or simplified. In real scenarios, detail completion must be configured, otherwise downstream order line items will be largely missing.
Special handling for empty Target: This strategy's Target is configured as "empty write operation", which is a pure query strategy. It usually serves as the "data preparation" stage for downstream write strategies and must be ordered first in the dependency graph.
Semantic trap of status filter: status=0 means "do not filter by status", not "query orders with status 0". This is a common pitfall. The safe approach is to explicitly pass in the required status values.
Flattened fields preferred over object fields: Flattened fields like company_name and customer_phone are already flattened in the Xiaoman API. Use them directly without parsing company/customer objects, which significantly reduces mapping complexity.

Pitfall Retrospective

Missing Orders: A retail company in early go-live had start_time directly set to the previous sync completion time without considering that Xiaoman's server clock was about 30 seconds ahead of local time, causing about 10 orders to be missed daily. The fix was to roll back start_time by 2 minutes and add monitoring alerts.
Empty product_list: Multiple customers encountered the list API returning product_list as [], resulting in zero downstream line items. We solved this thoroughly by configuring a detail completion node that calls /v1/invoices/order/info with order_id to fetch complete line items.
Silent Token Expiration: Xiaoman tokens have a short validity period. One solution did not configure auto-refresh, and after several hours of operation, all API calls returned 401. Qeasy's authentication manager enables token auto-refresh and retry by default; it is recommended to explicitly enable this in the adapter.
Status Filter Misunderstanding: An engineer interpreted status=0 as "query draft status orders", when in fact it means "do not filter by status". The result returned all orders, triggering duplicate writes downstream. It was corrected by explicitly passing status=2,3.
Currency and Exchange Rate Conversion Errors: In multi-currency scenarios, amount was summed up directly without multiplying by exchange_rate, causing order total amount偏差. After the fix, an exchange rate conversion node was added to Qeasy's field mapper to uniformly convert to RMB.

When to Use

This API is suitable for sales order master data synchronization between CRM and ERP, order status and amount reconciliation, and line item detail completion scenarios. It is not suitable for scenarios requiring real-time order creation (use the order creation API instead) or large file attachment transfer (use a dedicated attachment API). When the business is dominated by "T+1 batch reconciliation" or "near-real-time incremental synchronization", this API is the preferred entry point.

Authoritative Tutorial: Query Xiaoman Sales Order API Field Handbook