Changjietong T+ Inventory Archive Query API Tutorial: From Field Mapping to Qeasy Cloud Configuration

What This API Solves

In supply chain integration scenarios between WMS and Changjietong T+, the inventory archive (material master) is the foundation for all downstream document synchronization. We need to reliably pull product codes, specifications, multi-units, and batch attributes from T+ into the middleware layer, then distribute them to frontend business systems. This API serves as the core entry point for "master data broadcasting."

API Capability Overview

• Endpoint: /tplus/api/v2/inventory/Query
• Authentication: Changjietong T+ standard OAuth/account authorization, encapsulated by the Qeasy Cloud adapter
• Request Method: POST, JSON Body
• Key Parameters: MadeRecordDate (archive date, incremental anchor), Disabled (filter disabled items), PageSize/PageIndex (pagination)
• Response Structure: Root node returns an inventory array; each record contains ID, Code, Name, and object-type fields (InventoryClass, Unit, UnitByPurchase, etc.)
• Pagination: Traditional page-based, recommended max 200 per page
• Incremental Pattern: Uses MadeRecordDate as the time anchor, combined with Qeasy Cloud's "last sync time" variable (e.g., {{LAST_SYNC_TIME|date}}) for near-real-time incremental pulls
• Execution Schedule: Typical cron job is 36 3 * * *, running during low-peak hours

Typical Field Mapping

How to Configure on Qeasy Cloud

In the Qeasy Cloud data integration platform, this API is typically called using a combination of the T+ adapter and field mapper:

• Adapter Layer: Select the "Changjietong T+" connector, fill in account authorization info, and the platform automatically maintains token refresh.
• Strategy Type: Use "QUERY_ONLY" mode, configure the Target side as "write null operation" to sink data into Qeasy Cloud's intermediate table.
• Incremental Variable: Qeasy Cloud's field mapper automatically injects {{LAST_SYNC_TIME|date}} into the MadeRecordDate field of the request body, no scripting required.
• Object Expansion: For object-type fields like InventoryClass and UnitByPurchase, Qeasy Cloud provides "dot path" syntax (e.g., InventoryClass.Code) for direct value extraction.
• Scheduled Task: Set Cron to 36 3 * * * in the strategy, offset from upstream database backup rhythm.

Cross-Scenario Practical Points

1. Code over internal key: Always use Code for cross-system mapping; use ID only for idempotent deduplication within Qeasy Cloud to avoid broken links caused by T+ account migration.
2. Stable incremental anchor: Across multiple customer projects, the format of MadeRecordDate must be explicitly agreed (e.g., yyyy-MM-dd HH:mm:ss), with timezone based on T+ server location.
3. Multi-unit by scenario: Sales document sync uses UnitBySale, purchasing uses UnitByPurchase, inventory takes UnitByStock, never default to BaseUnitCode.
4. Filter disabled archives: T+ still returns disabled inventories; recommend fixing Disabled=false in request parameters to reduce invalid downstream data.
5. Expand object fields first: For InventoryClass, ProductInfo and other objects in Qeasy Cloud, use dot-path expansion, otherwise downstream will get stringified JSON.
6. Custom field passthrough: priuserdefnvc1~4 can be directly mapped to target system extension fields in Qeasy Cloud, no scripting needed.

Pitfall Review

• Pitfall 1: Timezone drift in MadeRecordDate. T+ server may return time without timezone; if Qeasy Cloud parses with local timezone, incremental data will be missed. The safe approach is to explicitly specify the T+ account timezone and fix the offset in Qeasy Cloud's time formatter.
• Pitfall 2: Object fields written as a whole. Dragging UnitBySale directly into the target field will serialize the entire object. Always expand to UnitBySale.Code and UnitBySale.Name in Qeasy Cloud's field mapper first.
• Pitfall 3: Pagination boundary causing duplicates. T+'s PageIndex starts from 1; if starting from 0, the first page will be skipped or duplicated. Qeasy Cloud's paginator defaults to starting from 1, but verify if customer scripts have modified this.
• Pitfall 4: Inconsistent Disabled field type. Some T+ versions return boolean, others return "true"/"false" strings. Use Qeasy Cloud's type converter to unify to boolean before writing to target.
• Pitfall 5: Custom field naming drift. After T+ upgrade, the semantics of priuserdefnvc1 may be redefined by customers. When reusing across accounts, add a "field semantic mapping table" in Qeasy Cloud, do not hardcode.

When to Use

This API is suitable for supply chain integration scenarios where Changjietong T+ material master data needs to be stably synchronized to e-commerce WMS or frontend business systems. If the business only involves document-level sync without master data governance, this can be skipped; if multi-unit, batch, or expiry management is involved, this API is essential infrastructure.