Authoritative Tutorial: Jushuitan Supplier Query API Field Handbook

What This API Solves

In retail and distribution scenarios, supplier master data is the foundation for purchase orders, purchase receipts, and purchase returns. When we integrate Jushuitan with Kingdee Cloud Skylight for supply chain workflows, we often need to pull Jushuitan supplier records into an intermediate layer and build code mappings with Kingdee's BD_Supplier, so as to support field mapping on subsequent purchase documents and supplier archive synchronization validation. This API is the standard entry point for querying Jushuitan supplier master data incrementally by modification time, serving as the "supplier linkage query" in supply chain integration.

API Capability Overview

The Jushuitan supplier query API /open/supplier/query is a POST endpoint, with strategy type QUERY (read-only, no write to target system).

• Authentication: Jushuitan Open Platform standard AppKey + signature mechanism. Business parameters and pagination parameters are carried in the request body.
• Request structure: Core parameters include modified_begin, modified_end (modification time range), page_index (page number, default 1), page_size (page size, default 50).
• Response structure: Returns a supplier list. Each record contains supplier_id, supplier_code, name, modified, group, enabled, etc.
• Pagination mode: Traditional pagination based on page_index + page_size; looping through pages is required until an empty array is returned.
• Incremental mode: modified_begin / modified_end combined with a scheduled task to capture changed data within a time window. The scheduled cycle is every 3 minutes (crontab */3 * * * *).

Typical Field Mappings

How to Configure on Qeasy

On the Qeasy Data Integration Platform, this API is typically invoked through a "Jushuitan Adapter + Field Mapper" combination:

• Data source configuration: Select the Jushuitan adapter, fill in the AppKey and signature. Choose /open/supplier/query as the endpoint, set strategy type to QUERY, and set Target to "no-op write" to indicate a read-only operation.
• Metadata configuration: Set supplier_id as both id (primary key) and number (code), so it can be referenced and mapped by subsequent documents.
• Incremental configuration: Bind modified_begin and modified_end to the "time window" parameters in Qeasy, using templates {{LAST_SYNC_TIME|datetime}} and {{CURRENT_TIME|datetime}}. The platform maintains the incremental cursor automatically.
• Pagination configuration: Bind page_index as a loop variable; page_size defaults to 50. Qeasy's loop runner automatically stops when an empty page is returned.
• Field Mapper: Qeasy's field mapper automatically exposes supplier_id, supplier_code, name, modified, group, enabled as output columns available to downstream nodes, making one-to-one mapping with Kingdee's FNumber, FName, etc. straightforward.

Cross-Scenario Practical Points

From multiple customer projects, we distilled the following common experience:

1. Dual role of supplier_id: Jushuitan's supplier_id serves as both primary key and code, which differs from many ERPs. In metadata, both id and number point to the same field. Keep them consistent during cross-system mapping.
2. Use modified as the incremental anchor: modified is the only time anchor for supplier archive changes. Do not use creation time, or you will miss updates. A 3-minute schedule is recommended.
3. Pagination and incremental must work together: Just paginating by page number will repeatedly pull historical data. The correct approach is to first filter by the modified range, then paginate within that range. Qeasy's loop runner follows this order.
4. Filter by the enabled field: Disabled suppliers should not be synced downstream. It is recommended to add a judgment in the mapper and only output records where enabled=true.
5. Maintain an independent mapping table for code mapping: The mapping between supplier_id and Kingdee FNumber should be kept in a separate mapping table rather than hard-coded inside the field mapper.
6. Set Target to no-op write: This strategy is read-only and does not write to the target system. Target must be "no-op write", or downstream data will be polluted.

Pitfall Recap

• Pitfall 1: Exiting before pagination completes — Only the first page was requested and it was mistakenly assumed that all data had been pulled, resulting in missing downstream supplier records. This is where things easily go wrong. The safe approach is to use Qeasy's loop runner to check whether the returned array is empty and break when it is.
• Pitfall 2: Using local timezone for incremental time — modified_begin/modified_end were passed with local time, causing a UTC offset from the server side, which led to missing or duplicate data. The correct approach is to consistently use UTC or Jushuitan server-side timezone.
• Pitfall 3: Treating supplier_id as a pure code — Only id was configured in metadata, with number omitted, causing downstream document references to fail to retrieve the code. Be sure to set both id and number to supplier_id.
• Pitfall 4: Syncing disabled suppliers as well — Suppliers with enabled=false were pushed into Kingdee, polluting the archive. Recommend adding a pre-filter in the mapper.
• Pitfall 5: Misconfiguring Target as a write — The Target of a read-only strategy was misconfigured as an actual write endpoint, causing data to be erroneously pushed downstream. Always confirm that Target is "no-op write".

When to Use

This API is suitable for supplier master data linkage query scenarios in Jushuitan and Kingdee Cloud Skylight (or similar ERP) supply chain integration, especially when incremental sync by modification time is needed, code mapping is required, and supplier field references must be provided for purchase documents. It is not suitable for scenarios where supplier archives need to be written or modified, nor for businesses with real-time requirements looser than 3 minutes.