> 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 月 6 日

這一版把規格（SKU）與商品分開：規格與組合品以料號識別，不一定要放在商品底下。其中組合品的識別序號與價格路徑是**破壞性變更**，已經串接組合品的整合需要調整。

## 規格可以只用料號同步

* `POST /v1/skus` 與 `POST /v1/skus/batch` 的 `productId` 改為選填。省略（或帶 0）就建成未加入商品的規格，查詢時 `productId` 為 0。
* 只帶料號、沒有 `id` 時，會在整個租戶內比對料號，**同一料號的每一顆規格都會更新**，所屬商品不變；找不到才新增。只管料號的 ERP 可以重複推送同一份資料，第一次新增、之後都是更新。
* 單筆回應改為 `{ "id": 5001, "ids": [5001] }`，所有批次寫入的逐筆結果也多了 `ids`：列出這一筆新增或更新的每一個序號，`id` 是其中第一個。
* 依 `id` 指定的更新帶 `"productId": 0` 會回傳 400，要保留所屬商品就不要送這個欄位。
* `GET /v1/skus` 會列出未加入商品的規格，`productId=0` 可以只篩出這些規格。
* 移除 `productId is required to create a SKU` 與 `bundle product cannot receive SKUs through this API` 兩個錯誤；料號只屬於組合品時改回 `outerSysCode belongs to a bundle SKU; use /v1/bundles`。

## 規格與組合品的狀態可以寫入

規格與組合品的建立、更新與批次寫入新增 `status` 欄位，接受 `Active`（上架）、`Inactive`（下架）、`GiftOnly`（僅供贈品），不分大小寫。省略時，新增為 `Active`、更新保留現有值；其他值回傳 `400 invalid_status`，批次只有該筆失敗。

## 移到另一個商品時比照後台

用 `productId` 把規格或組合品移到另一個商品時，規則與後台相同：排到目標商品的最後一個、客戶價格設定跟著移過去，原商品底下若已經沒有任何規格且狀態是上架或下架-顯示，會自動改為下架。

## 新建的商品一律下架

`POST /v1/products` 與 `POST /v1/products/batch` 新建的商品一律是 `Inactive`，請在後台確認內容後再上架。過去以組合商品建立的商品，現在也是一般商品頁，可以在「商品」端點查詢與更新。

## 庫存可以用料號推送

`POST /v1/skus/stock/batch` 的每一筆可以只帶 `outerSysCode`，租戶內同料號的每一顆規格都會設成同一個在庫數。回應改為一顆規格一列，並帶回請求的 `outerSysCode`，所以列數可能多於請求筆數。

## 新增客戶帳號 API

你現在可以替客戶管理前台登入帳號：`/v1/companies/{id}/users` 提供查詢（單筆與分頁清單）、建立與更新，`GET /v1/company-user-roles` 列出可以指派的角色。規則與在後台維護客戶帳號相同。

* 帳號在整個租戶內不得重複，不只是同一家客戶。新帳號會自動產生邀請碼，並依貴租戶的首次登入設定決定是否要求改密碼。
* 改派角色會讓帳號立即登出並清空購物車；設為 `Inactive` 也會立即登出。沒有刪除端點，停用帳號請用 `status`。
* 每一家客戶至少要保留一個生效中的 Boss 帳號，移除最後一個會回傳 `409 last_active_boss`。
* 網址上的客戶找不到時回傳 `404 company_not_found`，帳號找不到時回傳 `404 not_found`。

端點說明見「API 規格」的「客戶帳號」與「客戶帳號角色」，新增的錯誤字串見「錯誤碼」。

## ⚠️ 組合品改以組合 SKU 序號識別

組合品現在是一顆組合 SKU 加一份配方，可以放在任何商品頁底下，也可以不放。

* `/v1/bundles` 路徑上的 `{id}`、請求的 `id`、回應的 `id`／`ids`，以及 `PUT /v1/bundle-prices/batch` 的 `bundleId`，**全部改為組合 SKU 序號**，不再是商品序號。請重新用 `GET /v1/bundles` 取得序號。
* 回應移除 `skuId`（它就是 `id`）與 `productCategoryId`，新增 `productId`（所在商品頁，0 代表沒有放在商品頁）。
* 請求移除 `productCategoryId`，改為選填的 `productId`。舊版客戶端仍然送 `productCategoryId` 不會被拒絕，會被忽略。
* 只帶料號時與規格一樣比對整個租戶，同料號的每個組合品都會更新。料號屬於一般規格時回傳 `400 product_type_conflict`；商品端點不再回這個代碼。

## ⚠️ 組合品價格改為單數路徑

`GET /v1/bundles/{id}/prices` 改為 `GET /v1/bundles/{id}/price`，與 `GET /v1/skus/{id}/price` 一致。舊路徑沒有保留別名，會回傳 404。`PUT /v1/bundle-prices/batch` 路徑不變。

文件站台的「組合商品」同步改稱「組合品」。各端點的完整規則見「API 規格」，新增與移除的錯誤字串見「錯誤碼」，料號比對規則見「Upsert 與冪等」。