Authoritative Tutorial on the Xbongbong Product Query API: Field Handbook for Jushuitan × Xbongbong Master Data Integration

What This API Solves

In Jushuitan × Xbongbong master-data integration, products anchor sales orders, quotations, and opportunities. The /pro/v2/api/product/list endpoint paginates the Xbongbong product list. Typical uses are syncing Xbongbong products into Jbmsuitan goods and feeding mapping/lookup tables. It is read-only and commonly drives downstream master-data governance.

Capability Overview

• Auth: Standard Xbongbong OpenAPI auth; the body carries corpid and userId for tenant and operator identification.
• Method: POST, JSON body.
• Key Inputs: page (default 1), pageSize (default 100), conditions (filter), viewApproval (include pending approvals, 1/0), corpid, userId.
• Response: A wrapped envelope; business data lives in result.list. Each record carries dataId, data, addTime, updateTime, formId.
• Pagination / Incremental: Traditional page + pageSize paging; incremental syncs can rely on updateTime time windows.
• Strategy Type: QUERY_ONLY. Target is configured as "write-no-op," landing data in the Qeasy staging layer only.

Typical Field Mapping

Configuring in Qeasy

In the Qeasy Data Integration Platform, this API is usually exposed as a "Query Adapter." Selecting the Xbongbong product source auto-loads /pro/v2/api/product/list with a prefilled request template. In the field mapper, map dataId to the primary-key column and data.serialNo to the code column. result.list is auto-flattened into rows, and pageSize defaults to 100 but is tunable for stress tests. Set the target to "no-op" to preserve the read-only semantics, and schedule with a business-hours cadence such as */30 8-20 * * *.

Cross-Scenario Lessons

1. Use dataId as the primary key and data.serialNo as the business key. Roles are stable across scenarios: the primary key handles dedup, the business key powers Jushuitan goods mapping. Don't mix them up.
2. Flatten data before mapping. In Qeasy's field mapper, expand data and pick only what you actually need rather than dumping the whole JSON into a target field.
3. updateTime is more incremental-friendly than addTime. Products change prices and categories far more often than they are created, so a time window on updateTime cuts request volume significantly.
4. Page size is not "the bigger the better." pageSize=100 is a safe default. Too large risks Xbongbong throttling; too small inflates request count. In real projects it usually lands between 50 and 200.
5. viewApproval decides whether to wait for approvals. If the downstream sync demands "products in use," pass 0 to exclude pending approvals and avoid dirty data entering Jushuitan.
6. Use formId to isolate multi-form / multi-line businesses. In groups running several Xbongbong forms, formId is the key signal of product ownership—don't ignore it.

Pitfalls & Fixes

• Pitfall 1: Treating data.serialNo as the primary key. serialNo may be empty or changed, causing key drift. Keep dataId as PK and data.serialNo as business key only.
• Pitfall 2: Misaligned updateTime time zones. If the timestamp carries a timezone but the consumer parses it as local time, increments miss data. Normalize timezones centrally in Qeasy.
• Pitfall 3: Relying on the default viewApproval. Behavior varies across environments when omitted; pass 0 or 1 explicitly to avoid dirty data.
• Pitfall 4: Treating empty result.list as success. Handle empty pages separately—don't let an incremental run misread "no changes" and skip the next pull.
• Pitfall 5: Writing the entire data object into the target. This pollutes Jushuitan goods fields and trips downstream validation. Pick fields precisely in the mapper.

When to Use

This API fits one-way sync where Xbongbong is the product master source and Jushuitan is the downstream goods store. It also works well for initial master-data inventory. For two-way sync or complex business validation, layer write-side strategies on top rather than overloading this read-only endpoint.