Authoritative Tutorial on the Yonyou YS Inventory Price Query Interface Field Handbook

What Problem Does This Interface Solve

In the inventory synchronization chain between Yonyou BIP and Yonyou YS, the "Query Inventory Price" interface handles the retrieval of price master data. It returns the inventory/sales price of a material under a given accounting entity along the "organization + material" dimension, enabling the BIP side to perform price comparison, inventory valuation, and price master data synchronization. The strategy type is QUERY, which only retrieves data without writing back—making it a classic "pull-only" data object.

Interface Capability Overview

• Authentication: Yonyou YS open platform WebAPI, tenant-level application credentials (client_id/client_secret). Obtain an access_token via OAuth before invoking the API.
• Request Method: POST, with Content-Type set to application/json.
• Request Body: Primarily query conditions, typically including organization code, material code, and effective date range.
• Response Structure: Returns a list of material prices. Each record contains fields such as id, material, accentity, price, mainunit, and busitime. The metadata designates id as the primary key.
• Pagination/Incremental: Supports conditional pagination. For incremental checks, use pubts (publish timestamp) or busitime (business time); the landing side should deduplicate by pubts and filter by busitime.
• Scheduling: A typical crontab is 13 2 * * *, executing daily in the early morning.

Typical Field Mapping

How to Configure on Qeasy Cloud

On the Qeasy Cloud Data Integration Platform, this interface is typically integrated via a "source system adapter + field mapper" approach.

• Adapter Layer: Select the Yonyou YS query interface template, configure application credentials and the target organization list.
• Field Mapper: The platform automatically applies default mappings based on the generic concept mapping in this handbook (e.g., accentity → org_id, price → unit_price, mainunit → base_unit_id). Engineers only need to supplement the matching rules for the target-side BIP material primary key.
• Scheduling Configuration: Qeasy Cloud has a built-in crontab editor—simply enter 13 2 * * *. Alternatively, a trigger-based schedule using "last successful time + interval" can be used.
• Landing Strategy: The Target is configured as "write empty operation," so the platform only performs intermediate caching, allowing downstream BI or BIP consumers to access data on demand.

Cross-Scenario Practical Points

1. Always filter by organization: Prices are organization-specific. Without filtering by accentity_code, the full dataset will be returned, posing significant volume and permission risks.
2. price is a string: Direct storage as a numeric type will cause precision loss. It is recommended to configure Decimal conversion in the mapper and apply truncation per mainunit_Precision.
3. id is the unique primary key: Prefer id for deduplication and idempotency. Use pubts only as an incremental aid; do not treat pubts as the primary key.
4. Primary key and business code coexist: material (internal code) is the system key, while material_code is the business key. Both should be persisted during cross-system synchronization to facilitate subsequent maintenance.
5. Use pubts for incremental sync: Compared to busitime, pubts is more stable and less likely to cause missing data due to business time backwrites.
6. Stagger early-morning schedules: The 02:13 time slot often collides with other upstream inventory sync tasks. It is advisable to stagger schedules based on the overall task chain.

Pitfall Recap

• Pitfall 1: Using price directly as a numeric value, causing truncation for amounts with more than 8 digits. Solution: Force conversion to Decimal in the Qeasy Cloud field mapper and truncate per precision.
• Pitfall 2: Failing to pass organization filter conditions, pulling the entire group's prices at once and triggering upstream rate limits. Solution: Solidify an organization whitelist in metadata first.
• Pitfall 3: Using material_name as a match key, leading to many-to-one mismatches due to duplicate names. Solution: Always use material_code or material as the key.
• Pitfall 4: Treating busitime as the incremental cursor, causing entire batches to be missed after business time backwrites. Solution: Switch the incremental cursor to pubts.
• Pitfall 5: Ignoring mainunit_Precision, causing mismatches between price list prices and inventory quantity precision. Solution: Attach a precision conversion script in the field mapper.

When to Use

Applicable to "pull-type" integrations in the Yonyou BIP and Yonyou YS inventory synchronization scenario where material prices need to be retrieved—especially for price comparison, inventory valuation, and price master data synchronization. If prices need to be written back to a downstream ERP or price list system, choose a strategy type that supports write operations, not QUERY_ONLY.