Kingdee YXC Inventory Query API Field Handbook: Cross-Solution Practices to Stocktake Reconciliation

What This API Solves

In multi-system retail and distribution scenarios, ERP and WMS stock data often drift apart, leading to mismatched books and repeated stocktake corrections. The Kingdee YXC Instant Inventory API (SCM Inventory) exists precisely to push the ERP-side inventory baseline into a WMS-side stocktake document — using ERP as the source of truth and syncing quantities, batches, bins, and auxiliary attributes into the Qushuijade stocktake document so that one stocktake reconciles the books in a single pass.

API Capability Overview

• Authentication: Kingdee YXC Open Platform OAuth 2.0. Obtain an access_token first, then send it as a Bearer token in the request header.
• Request Method: POST /jdy/v2/scm/inventory/list, JSON body.
• Core Inputs: modify_start_time / modify_end_time (millisecond timestamps, standard incremental window), page, page_size, plus optional filters such as material_id / stock_id.
• Response Structure: A paging object containing data (the inventory list) and total_count. Each inventory object covers item, warehouse, bin, auxiliary attribute, batch, shelf life, and quantity dimensions.
• Pagination Model: Classic page-number pagination (page + page_size), default page size 10. Callers are advised to raise it to 50–200 to reduce round trips.
• Incremental Strategy: Pull by modify_time with a sliding window built from platform variables {{LAST_SYNC_TIME}}000 and {{CURRENT_TIME}}000.

Typical Field Mapping

How to Configure on Qeasy

On the Qeasy data integration platform, this API is wrapped as the "Kingdee YXC V2 SCM Inventory Adapter." The standard configuration path is as follows:

1. Adapter Selection: Source system "Kingdee YXC V2", interface "Inventory Query."
2. Metadata Binding: Bind id to material_id, number to material_number, and enable idCheck and autoFillResponse.
3. Field Mapper: In the visual mapping canvas, map material_number → items.sku_id, stock_number → warehouse, qty → items.qty. The Qeasy field mapper automatically handles type conversion and null-value fallbacks.
4. Scheduling: Set the cron to */25 * * * * (every 25 minutes); the incremental window uses the built-in variables {{LAST_SYNC_TIME}}000 / {{CURRENT_TIME}}000.
5. Target Configuration: Pick the Qushuijade stocktake upload interface, set type=check (full overwrite), is_confirm=1, so_id to {{random}}, and remark to "Kingdee Instant Inventory Sync."

Cross-Solution Practices

1. Composite Key Awareness: Across multiple customer projects, any inventory record involving batches or auxiliary attributes will silently lose data if you only use material_id + stock_id. Always add batch_no or aux_prop_id; for bin-managed warehouses, also add sp_id.
2. qty vs. valid_qty Choice: For stocktake reconciliation scenarios, always use qty (book balance) — do not let valid_qty (reserves deducted) mislead you, or the gap will keep growing.
3. Pre-map the Warehouse Dictionary: Qushuijade's warehouse is an enum (Kingdee codes must be translated into 1/2/3/4). Build the mapping table once in Qeasy's data-dictionary converter to avoid dirty data downstream.
4. Window for Batch / Shelf-Life Goods: Shelf-life-sensitive items must carry kf_date / valid_date into the stocktake document's remark or extension fields; otherwise the expiry judgment becomes unreliable.
5. page_size Tuning: Kingdee's default of 10 per page is very slow for large warehouses. We explicitly raise it to 100–200, which combined with the 25-minute window keeps pace with writes.
6. Resumable Pull: Persist the LAST_SYNC_TIME variable. Qeasy persists it automatically, but pay attention to time zone and midnight boundary when crossing days.

Pitfall Postmortems

1. No batch in strategy but deduped by batch_no: A retail client lost nearly 30% of records on their first stocktake because items had batches enabled but the strategy did not include batch_no in the dedup key, causing multiple records to overwrite each other.
2. Auxiliary attributes vs. Qushuijade SKU mismatch: For color/size items, Kingdee uses auxiliary attributes while Qushuijade uses SKUs. Mapping directly on material_id makes Qushuijade unable to recognize specs. The safe approach is to append aux_prop_number to the SKU code suffix.
3. valid_qty misused as stocktake baseline: Writing valid_qty into the stocktake quantity caused the stocktake variance to be "swallowed" by reservations, so books and stock never matched.
4. Whole vs. loose UoM confusion: qty_package and qty are in different units. If you only take qty for whole-package-managed items, you under-count by half. Always select the field according to the item's UoM policy.
5. Cross-time-zone timestamp drift: The incremental window occasionally missed data across midnight because Kingdee returns modify_time in UTC+8 while the scheduler assumed UTC. The safe approach is to format the window variables in Asia/Shanghai consistently inside Qeasy.

When to Use

Choose this API when the enterprise treats ERP as the single inventory source of truth and needs to sync that baseline into a WMS stocktake document for a one-shot reconciliation. If you only need a stock alert or coarse dashboard, consider Kingdee's lightweight BI interface. If the systems already share an isomorphic inventory model, skip the stocktake route and use the inventory transfer interface instead.