YonBIP Sales Order Query API Field Handbook: Authoritative Tutorial

What This API Solves

The YonBIP Sales Order query API (/yonbip/sd/voucherorder/list) is the core entry point for CRM-ERP sales order integration. Typical scenarios include syncing order status from Xiaoman OKKI CRM to the ERP, or pulling order details from the ERP back to the CRM for full-chain visibility. This API returns detail-line level flattened data, ideal for line-level inventory, batch, and price reconciliation.

API Capabilities Overview

• Authentication: Standard YonBIP OAuth, with access_token required in the request header.
• Request Structure: HTTP POST with a JSON body. Core parameters: pageIndex (default 1), pageSize (default 50), open_vouchdate_begin/end (incremental time window), code (order number), nextStatusName (status filter).
• Response Structure: A flattened array is returned. In the metadata, id maps to orderDetailId (detail primary key), and number maps to code (order number).
• Pagination: Traditional pagination — loop pageIndex until an empty array is returned.
• Incremental Mode: Rolling window based on open_vouchdate_begin to open_vouchdate_end. Production scheduling is typically */7 8-18 * * * (every 7 minutes during business hours).
• Special Flags: isSum=false returns detail lines; true aggregates by header.

Typical Field Mappings

How to Configure on Qeasy

Qeasy Data Integration Platform provides a complete adapter wrapper for the YonBIP Sales Order API:

• Adapter: On Qeasy, this API is typically invoked via the prebuilt "YonBIP-Sales Order Query" connector. Just fill in tenant and AppKey to enable — no manual OAuth refresh logic required.
• Field Mapper: The platform automatically recognizes the metadata mapping id → orderDetailId and number → code. In the mapping canvas, you can directly drag orderDetailId as the target system's unique key.
• Incremental Strategy: The configuration panel supports visual setup of open_vouchdate_begin/end offset variables (e.g., {{DAYS_AGO_30|date}}), combined with the scheduler */7 8-18 * * * for rolling fetches.
• Pagination Loop: Qeasy has a built-in pagination iterator that auto-loops on pageIndex and writes to the target database, automatically terminating when an empty page is returned.
• Deduplication: Recommend writing with orderDetailId as the primary key. The platform performs UPSERT by primary key, avoiding duplicate rows.

Cross-Scenario Best Practices

1. Detail-line granularity is the default: The YonBIP Sales Order API returns flattened "header+body" detail lines — not header-aggregated data. If the business side needs order-level status, secondary aggregation by id/orderId is required.
2. Wrong primary key causes full reload: In real scenarios, it is easy to mistakenly treat id as the unique key. But multiple product lines of the same order share id, causing duplicate inserts downstream. The safe approach is to always use orderDetailId.
3. Status enums must be translated: nextStatus and payStatusCode are English enum values. Passing them directly to business users will cause issues. Build an enum mapping table (e.g., CONFIRMORDER → Created, FINISHPAYMENT → Paid).
4. Incremental field priority: When vouchdate (order date), orderDate (creation date), and pubts (system timestamp) all exist, prioritize vouchdate for incremental filtering — it has the clearest semantics. Use pubuts as auxiliary deduplication.
5. Amount field pairing validation: payMoney (header tax-incl. total) should equal the sum of each line's oriSum. Large discrepancies usually indicate gift lines (MARKUP/REBATE) were not excluded. Filter by orderProductType.
6. Multi-org permissions: Customers with multiple sales organizations must filter by salesOrgId; otherwise the API returns all data, which is slow and carries authorization risks.

Pitfall Postmortem

• Pitfall 1: Pagination infinite loop. When pageSize is too large (e.g., 1000) and gets truncated by the server, the empty-array check fails and triggers infinite fetching. The safe approach is Qeasy's built-in "consecutive empty pages exceed N → auto-circuit-break" mechanism, or keep pageSize under 200.
• Pitfall 2: Missing incremental records. When fetching by open_vouchdate_begin, timezone mismatch between upstream and downstream causes early-morning orders to be missed. Solution: extend the time window by 2 hours and use pubuts for secondary compensation.
• Pitfall 3: Status stuck on APPROVING. Orders under approval have no subsequent status push; the integration side keeps showing "In Approval". The common pitfall is forgetting to monitor the auditDate field — once approval completes, actively pull the latest status.
• Pitfall 4: Gift lines double-counted in receivables. Lines with orderProductType=GIFT have non-zero oriSum. Summing them directly counts gifts into receivables. Always add the filter orderProductType != 'GIFT' in the mapper.
• Pitfall 5: Missing batch field. For batch-managed products, if batchNo is empty, downstream WMS cannot issue goods. On Qeasy, configure "non-null validation" in the field mapper to alert on missing values.

When to Use This API

This API suits CRM-ERP sales order bidirectional sync, order status dashboards, line-level sales analysis, and inventory pre-allocation scenarios. Not suitable for: order-header aggregate statistics only (use isSum=true instead), real-time single-order queries (use the order detail API), or one-time historical full migration (use batch export). When business requires line-level reconciliation across products, batches, and warehouses, this API is the best choice.