Skip to navigation

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