Skip to navigation

追蹤文件站台與 API 的異動

這裡記錄 OrderUp B2B Open API 文件站台與底層 API 的重要異動——新端點、行為調整、修正。可以依標籤篩選項目,也可以透過 RSS 訂閱。

2026 年 11 月 14 日

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

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

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

端點舊欄位新欄位
GET /v1/skus、GET /v1/skus/{id}inventoryQtyinventoryQuantity
GET /v1/skus/{id}/stock、GET /v1/bundles/{id}/stockinventoryQty、availableQtyinventoryQuantity、availableQuantity
POST /v1/skus/stock/batch、POST /v1/bundles/stock/batch 的每一筆quantityinventoryQuantity
releasev1breaking

2026 年 11 月 11 日

這一版讓組合品有自己的庫存額度,並新增組合品庫存 API。既有組合品的庫存行為會改變,已經串接組合品的整合請先看最後一節。

組合品有自己的庫存額度

組合品要能下單,現在兩關都要過:組合品自身的額度,以及各組成規格的庫存。

  • isNegativeStockAllowed 為 true 時,組合品自身不限量,只看組成規格,與過去相同。
  • 為 false 時,組合品自身的可售數(在庫數扣掉未出貨訂單佔用)用完就不能再下單,即使組成規格還有庫存。適合限量禮盒這類情境。
  • 出貨時組合品自身的在庫數會跟著扣減,出貨後取消會回補,與一般規格相同。
  • 組合品自身的額度不會產生預購數量,預購只由允許負庫存的組成規格計算。
releasev1breaking

2026 年 11 月 9 日

客戶可以用業務代碼指定負責業務

POST /v1/companies、PUT /v1/companies/{id} 與 POST /v1/companies/batch 新增選填欄位 internalUserOuterSysCode:用負責業務(內部使用者)的 outerSysCode 指定人選,不必先查出他的序號。

  • 同時帶 internalUserId 與 internalUserOuterSysCode 時以 internalUserId 為準,代碼完全不會被比對。
  • 代碼與貴租戶底下未刪除的內部使用者精準比對,前後空白會被忽略、大小寫敏感;只有空白視同省略。
  • 代碼對不到任何人回傳 400 internal_user_not_found,對到兩位以上回傳 400 internal_user_code_ambiguous。兩種情況都不會退回預設業務,也不會寫入任何欄位;批次只有該筆失敗。
  • 兩個欄位都省略時行為不變:新增套用預設業務,更新保留現有值。
releasev1

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。
releasev1breaking

2026 年 11 月 4 日

客戶可以寫入結帳條件與付款方式

POST /v1/companies、PUT /v1/companies/{id} 與 POST /v1/companies/batch 新增三個欄位:settlementType(Cash 現結/Monthly 月結)、paymentMethodMode(Inherit/Specify)與 paymentMethods。這三個欄位原本只能讀取,現在可以由 ERP 直接維護,規則與後台客戶維護相同:

  • 省略時,新增的客戶為 Monthly、Inherit、空清單;更新時保留現有值。
  • paymentMethodMode 與 paymentMethods 須成對寫入:Inherit 會清空清單,Specify 必須在同一個請求帶非空清單。
  • Specify 實際生效的是清單與租戶目前已啟用付款方式的交集。
  • 驗證失敗回傳 400 加上對應的錯誤字串,整筆不寫入;批次寫入則是那一筆回報 failed。
releasev1

2026 年 11 月 3 日

後台使用者支援批次更新

新增 PUT /v1/internal-users/batch,可以用 ERP 端的使用者代碼(outerSysCode)或使用者序號(id)一次更新多位後台使用者,不必先存下 OrderUp 的序號:

  • 每一筆有 id 就用 id 找出要更新的使用者,沒有 id 才用 outerSysCode;其餘欄位的部分合併規則與 PUT /v1/internal-users/{id} 相同。
  • 同時帶 id 與 outerSysCode 時,outerSysCode 會被寫入成這位使用者的新代碼,可以順便把 ERP 代碼綁上既有使用者。
  • 只更新、不新增;只帶 outerSysCode 時,代碼只是用來找人的鍵,不會被改寫。
  • 同租戶內有兩位以上的使用者用同一個代碼時,該筆回報 ambiguous_outer_sys_code 且不寫入,其他筆照常處理。
releasev1

2026 年 9 月 9 日

文件站台首次發布

OrderUp B2B Open API 文件站台正式發布,涵蓋 12 個資源家族、共 36 支 /v1 端點:

  • 客戶——查詢清單、查詢單筆、建立、更新、批次寫入
  • 點數額度——查詢、批次同步
  • 合約額度——查詢、批次同步
  • 商品分類——查詢分類樹(唯讀)
  • 商品——查詢清單、查詢單筆、建立、更新、批次寫入
  • 規格(SKU)——查詢清單、查詢單筆、建立、更新、批次寫入
  • 規格(SKU)價格——查詢、批次更新
  • 組合商品——查詢清單、查詢單筆、建立、更新、批次寫入
  • 組合商品價格——查詢、批次更新
  • 庫存——查詢單一規格庫存、批次更新庫存
  • 後台使用者——查詢清單、查詢單筆、建立、更新
  • 後台角色——查詢清單(唯讀,不分頁)
releasev1