追蹤文件站台與 API 的異動
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 與冪等」。