> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.orderupb2b.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.orderupb2b.com/_mcp/server.

# 2026 年 11 月 14 日

這一版統一庫存欄位的命名，並把可組數量從組合品主檔移除。兩項都是破壞性變更，有串接庫存或組合品的整合請在上線前調整。

## ⚠️ 庫存欄位統一改名為 inventoryQuantity

同一個「在庫數」過去在查詢時叫 `inventoryQty`、在批次寫入時叫 `quantity`，現在一律叫 `inventoryQuantity`；可售數也跟著改成 `availableQuantity`。

| 端點                                                              | 舊欄位                           | 新欄位                                     |
| --------------------------------------------------------------- | ----------------------------- | --------------------------------------- |
| `GET /v1/skus`、`GET /v1/skus/{id}`                              | `inventoryQty`                | `inventoryQuantity`                     |
| `GET /v1/skus/{id}/stock`、`GET /v1/bundles/{id}/stock`          | `inventoryQty`、`availableQty` | `inventoryQuantity`、`availableQuantity` |
| `POST /v1/skus/stock/batch`、`POST /v1/bundles/stock/batch` 的每一筆 | `quantity`                    | `inventoryQuantity`                     |

* 批次寫入**不再讀取舊的 `quantity`**。繼續送 `quantity` 不會報錯，而是被當成沒帶：在庫數維持現值、不留異動紀錄；如果該筆也沒帶 `isNegativeStockAllowed`，會回報 failed。請務必改送 `inventoryQuantity`。
* 兩個欄位都沒帶時的錯誤字串由 `quantity or isNegativeStockAllowed is required` 改為 `inventoryQuantity or isNegativeStockAllowed is required`。有比對這個字串的整合需要調整。
* 組合品配方的每組用量（`components[].quantity`）與數量精度（`quantityPrecision`）不是庫存欄位，名稱不變。

## ⚠️ 組合品主檔移除可組數量

`GET /v1/bundles` 與 `GET /v1/bundles/{id}` 的回應不再有 `availableQty`（以目前庫存最多能組出幾份）。組合品主檔現在不回傳任何庫存數字。

* 組合品自身的在庫數與可售數，請改查 `GET /v1/bundles/{id}/stock`。
* API 不再提供可組數量；需要時請用各組成規格的 `GET /v1/skus/{id}/stock` 與配方的每組用量自行計算。

各端點的完整規則見「API 規格」的「庫存」「組合品庫存」「組合品」，錯誤字串見「錯誤碼」。