> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.orderupb2b.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.orderupb2b.com/_mcp/server.

# 開始使用

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`**

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

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

分類樹通常只有兩層、根分類數十個，建議查一次後在你端快取，不需要每次建立商品前都重新查詢；後台角色（`GET /v1/internal-roles`）也是同樣的唯讀＋不分頁性質，適合快取。

## 下一步

#### [驗證與簽章](/authentication)

四個驗證標頭、canonical string 的組成、可核對的簽章範例，以及 401 排查清單

#### [分頁與篩選](/pagination)

清單端點的分頁形狀、篩選規則，以及商品分類樹的特殊分頁方式

#### [Upsert 與冪等](/upsert)

新增／更新／去重的三條規則，以及部分合併如何避免覆蓋既有資料