公開 API

1. API 使用範圍

a. API 支援的功能

公開 API 可與 Wholesale 應用程式的主要功能互動，包括：

• 核心功能：批發定價、數量定價、註冊表單、快速訂購表單、快速購買商品系列、快速購買款式
• 附加功能：訂單限制、運費、額外費用、付款條款（即將推出）

b. 支援的方法

API 支援下列 HTTP 方法的完整 CRUD 操作：

• GET – 擷取資料
• POST – 建立新資料
• PUT – 更新現有資料
• DELETE – 移除資料

API 金鑰可授予下列權限層級：Read Only/Write Only、Read & Write

支援的動作包括：Get list - Get item - Create item - Update item - Delete item

c. 支援的 Shopify 方案：

Wholesale 應用程式的公開 API 適用於符合下列條件的 Shopify 商店：

• 必須為正式商店（不適用於開發或測試商店）
• 必須訂閱 Gold 方案

---

2. 驗證

所有 API 請求都必須通過正確驗證才會被處理。

a. 必要參數

每個 API 請求都必須包含下列必要參數：

參數	說明
shop	Shopify 商店網域（例如 mystore.myshopify.com）
api_key	從 Wholesale 應用程式產生的 API 金鑰

若缺少其中任一參數，請求將會被拒絕。

b. API 金鑰管理

API 金鑰直接在 Wholesale 應用程式的管理介面中建立與管理。
商店擁有者可為每組 API 金鑰設定特定權限：Read only/Write only、Read & Write

---

3. API 結構與回應格式

a. API 端點

所有 API 請求都應使用下列基本網址：

https://wholesale.samita.io/v1/

b. 各功能專屬的端點

每個功能群組都有各自的端點。例如：

• Wholesale 功能：

  https://wholesale.samita.io/v1/wholesale/

• Volume Pricing 功能：

  https://wholesale.samita.io/v1/volume/

（實際端點可能因具體功能而異。）

c. 支援的查詢參數

API 支援數個常用的查詢參數：

參數	說明
status	紀錄的狀態
page	分頁的頁碼
limit	每頁的紀錄數
sort	排序條件
query	搜尋或篩選條件

請求範例：

GET /wholesale?page=1&limit=20&sort=created_at

---

4. 回應代碼

每個 API 請求都會傳回下列其中一種狀態碼：

a. 常見的錯誤回應

401 – Unauthorized

可能原因：

• 缺少商店網址
• 缺少 API 金鑰
• 商店網址無效
• API 金鑰無效
• API 金鑰與商店不符

---

403 – This action is unauthorized

• API 金鑰沒有執行所請求動作的權限
• View / Create / Update / Delete 權限不足

---

429 – Too Many Requests

• 已超過請求上限
• API 呼叫頻率超過允許的速率限制

---

b. 成功回應

200 – Success

• 請求有效
• API 動作已成功執行
• 資料以正確格式傳回

---

5. 速率限制

為確保系統效能與穩定性，API 的使用受每日請求上限限制。不再有單次請求／短時間間隔的節流限制，只要不超過方案的每日配額，您可隨時依需求呼叫 API。

每日上限取決於商店的定價方案：

方案	每日請求上限
Free	每天 5 次請求
Starter	每天 50 次請求
Growth	每天 250 次請求
Enterprise	每天 500 次請求

每日計數器會於每天午夜（伺服器時間）重設。

若超過每日上限，系統將傳回：

429 – Too Many Requests

{
  "message": "Daily request limit exceeded (X requests/day)."
}