開始使用

B2BStore External API 是供 ERP 系統與 OrderUp B2B 平台同步主檔與庫存的介接 API。透過這組 API，你可以從 ERP 端推送客戶、商品、規格（SKU）與庫存數量，也可以分頁查詢平台上既有的資料，用來核對 ERP 與 OrderUp B2B 兩邊的狀態是否一致。

所有 /v1 端點都需要簽章驗證，細節見「驗證與簽章」。

域名與憑證

本文件所有範例使用的網址 https://api.example.com 只是佔位符。實際的 API 網域、client_id 與 client_secret 由 OrderUp 在開通介接時個別提供，請勿沿用文件上的範例值。

第一個請求

拿到憑證後，建議先呼叫一個唯讀端點，確認簽章驗證能夠通過。以下示範查詢商品分類樹：

curl --location 'https://api.example.com/v1/product-categories' \
--header 'X-Client-Id: your_client_id' \
--header 'X-Timestamp: 1757400000' \
--header 'X-Nonce: 6f1a2b3c4d5e6f708192a3b4c5d6e7f8' \
--header 'X-Signature: <依「驗證與簽章」頁計算出的簽章>'

四個標頭缺一不可：X-Client-Id 是 OrderUp 配發的用戶端識別碼；X-Timestamp 是目前的 Unix 秒數；X-Nonce 是本次請求專用、不重複的隨機字串；X-Signature 則是用 client_secret 對這次請求計算出的 HMAC-SHA256 簽章，計算方式與逐步範例請見「驗證與簽章」。上面的 X-Timestamp、X-Nonce、X-Signature 只是示意格式，實際數值必須依當下時間與請求內容重新計算，不能照抄。

請求成功時會收到 200，body 是分頁格式的分類樹（{ data, totalCount, currentPage, pageSize, totalPages }）；若收到 401，代表簽章驗證沒有通過，請對照「驗證與簽章」頁最後的排查清單。

建議的介接順序

首次串接時，建議依照以下順序推送主檔，而不是任意順序混著送：

1. 商品分類（GET /v1/product-categories）—— 分類樹是唯讀的，建立或更新商品前必須先取得可指派的分類 id。
2. 商品（/v1/products）—— 建立商品時 productCategoryId 為必填，且必須是第 1 步取得的可指派分類；先有商品，第 3 步的規格才有 productId 可以掛。
3. 規格（SKU）（/v1/skus）—— 建立規格時 productId 為必填，且必須指向第 2 步已存在的商品；規格建立完成後才會有 skuId 可以在第 4 步寫入庫存。
4. 庫存（/v1/skus/stock/batch）—— 庫存端點只接受既有規格的 skuId，所以必須排在規格之後；規格本身的建立與更新端點永遠不會異動庫存，兩者刻意分開。
5. 客戶（/v1/customers）—— 客戶主檔與商品、規格、庫存之間沒有相依關係，不受前四步順序牽制，安排在最後可以讓「商品／規格／庫存」這條主檔鏈與「客戶」這條買方資料鏈各自獨立進行，互不阻塞。

簡單說：前四步是一條有相依關係的鏈（分類 → 商品 → 規格 → 庫存），每一步都需要上一步產生的 id；客戶則是獨立的一條線，什麼時候同步都可以，排在最後只是慣例上的安排。

下一步