Skip to navigation

開始使用

同步您的 ERP 或其他系統的資料到 OrderUp B2B

View as Markdown

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

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

域名與憑證

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

測試請求

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

curl
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 步取得的可指派分類。新建的商品一律是下架(Inactive)狀態,請在後台確認後上架。只管料號、不需要商品頁的 ERP 可以跳過這一步。
  3. 規格(SKU)(/v1/skus)—— 規格以料號(outerSysCode)識別,productId 是選填:省略就建成未加入商品的規格,之後在後台放進商品頁;要直接放進商品時,帶第 2 步已存在的商品序號。同一份資料可以只用料號重複推送,第一次新增、之後都是更新。
  4. 庫存(/v1/skus/stock/batch)—— 庫存端點用 skuId 或料號指定既有規格,所以必須排在規格之後;規格本身的建立與更新端點永遠不會異動庫存,兩者刻意分開。
  5. 組合品(/v1/bundles)—— 配方裡的每個元件都必須是第 3 步已經建立的一般規格,所以組合品至少要排在規格之後;組合品沒有可直接寫入的庫存欄位,與第 4 步的先後順序無妨。
  6. 客戶(/v1/companies)—— 客戶主檔與商品、規格、庫存、組合品之間沒有相依關係,不受前面步驟牽制,安排在最後可以讓「商品/規格/庫存/組合品」這條主檔鏈與「客戶」這條買方資料鏈各自獨立進行,互不阻塞。

簡單說:前五步是一條有相依關係的鏈(分類 → 商品 → 規格 → 庫存/組合品),後面的步驟需要前面已經存在的資料;客戶則是獨立的一條線,什麼時候同步都可以,排在最後只是慣例上的安排。

規格與組合品的價格如果之後要單獨調整,可以用 PUT /v1/prices/batch/PUT /v1/bundle-prices/batch 批次更新牌價與對外售價,不需要重新送整筆主檔;客戶建立後,若要同步點數或合約額度,可用 POST /v1/companies/point-quota/batch/POST /v1/companies/credit-quota/batch,兩者都是選用,未同步不影響客戶主檔本身。要替客戶開前台登入帳號,用 POST /v1/companies/{id}/users,角色序號先從 GET /v1/company-user-roles 取得。

分類樹通常只有兩層、根分類數十個,建議查一次後在你端快取,不需要每次建立商品前都重新查詢;後台角色(GET /v1/internal-roles)與客戶帳號角色(GET /v1/company-user-roles)也是同樣的唯讀+不分頁性質,適合快取。

下一步