拍賣平台的 API 設計：打造開放生態系

Q: API 版本要維護多久？

舊版本至少維護 6-12 個月。發布新版時同時公告舊版的 Sunset 日期，並在舊版的每個回應 header 加上 Sunset 和 Deprecation 標記。定期統計各版本的流量，當舊版流量低於 5% 時可以考慮正式下線。

你有沒有想過，為什麼 eBay 能變成一個「拍賣帝國」，而不只是一個拍賣網站？答案就藏在它的 API 裡。eBay 的開發者生態系有超過 16 萬個註冊開發者，每天處理超過 90 億次 API 呼叫。第三方賣家工具、價格追蹤器、自動出價機器人——這些全都是透過 API 建立起來的。

一句話總結：拍賣平台的 API 不是「給工程師用的後門」，是把你的平台從單點服務變成生態系的核心基礎設施。

聽起來很遙遠？其實不會。就算你的拍賣平台還在起步階段，從第一天就把 API 設計好，日後要擴展生態系時就不用砍掉重練。這篇文章會從頭帶你走一遍：為什麼要做 API、怎麼設計端點、認證怎麼處理、Webhook 怎麼推事件、速率限制怎麼定——全部都是拍賣場景的實戰考量。

拍賣 API 是什麼？跟一般電商 API 有什麼不同？

拍賣 API 是拍賣平台對外提供的程式介面，讓第三方應用程式能以程式化方式存取拍品資料、執行出價操作、接收即時事件通知。 跟一般電商 API 最大的不同在於：拍賣有「時間性」跟「競爭性」。

電商 API 的核心動作是「加入購物車 → 結帳」，這是線性的、不緊急的。但拍賣 API 的核心動作是「出價」——這個動作有時間限制（結標時間）、有競爭對手（其他買家）、有原子性要求（同一時間只能有一個最高出價）。

這表示拍賣 API 的設計要特別注意幾件事：

低延遲：出價 API 的回應時間必須控制在 200ms 以內，超過這個門檻，買家在最後幾秒搶標時會來不及
一致性：併發出價時，必須保證只有金額最高的那筆成功。這背後需要原子鎖機制
即時性：出價成功後，相關方（其他買家、賣家、第三方工具）要能即時收到通知

這三個特性，決定了拍賣 API 跟一般 CRUD API 有根本性的差異。

為什麼你的拍賣平台需要開放 API？

開放 API 不是大平台的專利，它是讓你的平台產生網路效應的槓桿。 想像幾個場景：

商家的 ERP 串接

你的平台入駐了 50 家商家，每家都有自己的庫存管理系統。如果沒有 API，商家要手動在你的後台上架拍品、手動更新狀態、手動處理結標後的出貨——光是想就累。有了 API，商家的 ERP 系統可以自動把商品推到你的平台、自動取得結標結果、自動觸發出貨流程。

第三方工具生態

價格追蹤器、出價提醒 App、拍品比較網站——這些工具都能為你的平台帶來額外流量。但前提是你有 API 讓這些工具的開發者串接。每多一個第三方工具，就等於多一個幫你推廣的管道。

數據分析與報表

數據分析儀表板如果只能看平台內建的報表，對大商家來說通常不夠用。API 讓他們可以把拍賣數據拉到自己的 BI 工具裡（Power BI、Tableau、Google Looker Studio），做更深入的分析。

跨平台聯播

同一件拍品可以同時在你的網站、合作夥伴的 App、甚至 LINE 官方帳號上架。API 讓「一次上架、多處曝光」成為可能。

拍賣 API 三層架構

RESTful 端點怎麼規劃？拍賣場景的特殊考量

RESTful API 的設計原則是以「資源」為核心，用 HTTP 方法表達操作意圖。 但拍賣場景有些地方需要特別處理。

核心資源與端點設計

# 拍品資源
GET    /api/v1/auctions              # 列表（支援篩選、排序、分頁）
POST   /api/v1/auctions              # 建立拍品（商家用）
GET    /api/v1/auctions/{id}         # 單一拍品詳情
PATCH  /api/v1/auctions/{id}         # 更新拍品（僅限未開始的）
DELETE /api/v1/auctions/{id}         # 撤銷拍品（僅限未開始的）

# 出價資源
POST   /api/v1/auctions/{id}/bids    # 出價
GET    /api/v1/auctions/{id}/bids    # 該拍品的出價記錄

# 使用者資源
GET    /api/v1/users/me              # 目前登入者資訊
GET    /api/v1/users/me/bids         # 我的出價記錄
GET    /api/v1/users/me/watchlist    # 我的追蹤清單
POST   /api/v1/users/me/watchlist    # 加入追蹤

出價 API 的特殊設計

出價不是一般的 POST 就好。回應格式要包含幾個拍賣專屬的欄位：

{
  "data": {
    "bid_id": "bid_9a8b7c6d",
    "auction_id": 2847,
    "amount": 1550000,
    "status": "accepted",
    "is_highest": true,
    "next_minimum_bid": 1600000,
    "auction_ends_at": "2026-03-27T15:30:00+08:00",
    "was_extended": false,
    "total_bids": 23
  }
}

注意 next_minimum_bid——這是拍賣平台獨有的概念。階梯加價規則讓每次出價都有最低門檻，API 回傳這個值，前端或第三方工具就不用自己算。was_extended 則對應防狙擊機制：如果這次出價觸發了延時，讓呼叫方知道結標時間變了。

分頁與篩選

拍品列表的 API 一定要支援完善的篩選，不然第三方開發者會崩潰：

GET /api/v1/auctions?status=active&category=watches&min_price=10000&max_price=50000&sort=ending_soon&page=1&per_page=20

分頁推薦用 cursor-based pagination 而不是 offset-based。拍品會不斷新增與結標，offset 分頁在資料頻繁變動時會出現重複或遺漏。

版本控制

URL 前綴加版本號（/api/v1/）是最直覺的做法。當需要破壞性變更時，發布 v2 版本，同時維護 v1 至少 6 個月，給開發者足夠的遷移時間。在回應 header 加上 Sunset 日期提醒舊版本即將下線。

認證與授權怎麼做才安全？

API 認證是把你家大門鑰匙交給外人之前，必須先做好的事。 做錯了，輕則被濫用，重則資料外洩。

三種認證機制的選擇

機制	適用場景	安全等級
API Key	只讀的公開資料存取	中
OAuth 2.0	需要存取使用者資料的第三方應用	高
JWT（Bearer Token）	自家前端與 App	高

對拍賣平台來說，建議同時支援 API Key 和 OAuth 2.0：

API Key：給價格比較網站、拍品聚合平台等只需要讀取公開拍品資料的服務
OAuth 2.0：給需要代替使用者出價、管理追蹤清單的第三方應用

OAuth 2.0 授權流程

權限範圍（Scopes）設計

OAuth 2.0 的 scope 要設計得夠細：

auctions:read — 讀取拍品資料
auctions:write — 建立/修改拍品（商家）
bids:read — 讀取出價記錄
bids:write — 執行出價（最敏感的權限）
users:read — 讀取使用者基本資料
webhooks:manage — 管理 Webhook 訂閱

bids:write 這個 scope 要特別謹慎——授權給第三方 App 代替使用者出價，等於把錢包交出去。建議加上額外的確認機制：首次授權時用 2FA 驗證、每次出價都需要使用者的 PIN 碼。

這部分跟拍賣網站的安全防護密切相關，API 層面的安全設計是整體資安架構的一環。

Webhook 怎麼設計？讓第三方即時收到拍賣事件

Webhook 是拍賣 API 最強大的功能之一——把「第三方來問」變成「平台主動推」。 比起讓開發者每隔幾秒 polling 你的 API 檢查有沒有新出價，Webhook 讓你在事件發生的當下就推送到對方的伺服器。

事件類型設計

拍賣平台的 Webhook 事件至少要涵蓋：

# 出價相關
bid.placed          — 有新出價
bid.outbid          — 某人被超價
bid.auto_extended   — 觸發防狙擊延時

# 拍品相關
auction.created     — 新拍品上架
auction.started     — 拍品開始接受出價
auction.ending_soon — 即將結標（可設定閾值）
auction.ended       — 結標
auction.cancelled   — 拍品撤銷

# 交易相關
payment.completed   — 付款完成
payment.overdue     — 付款逾期
shipment.sent       — 已出貨
shipment.received   — 買家確認收貨

Payload 設計原則

Webhook 的 payload 不要只丟一個 ID 叫對方再來查——這樣等於讓對方多打一次 API，浪費彼此的資源。包含足夠的資訊讓接收方直接處理：

{
  "event": "bid.placed",
  "timestamp": "2026-03-27T14:23:15+08:00",
  "data": {
    "bid_id": "bid_9a8b7c6d",
    "auction_id": 2847,
    "auction_title": "LV Speedy 25 經典老花手提包",
    "amount": 1550000,
    "previous_amount": 1500000,
    "bidder_count": 23,
    "ends_at": "2026-03-27T15:30:00+08:00",
    "was_extended": false
  }
}

金額用「分」為單位（integer），避免浮點數精度問題——NT$ 15,500 存成 1550000。這跟資料庫設計中的金額儲存策略一致。

安全機制：簽章驗證

每個 Webhook 請求都要帶簽章，讓接收方驗證「這真的是你的平台送的」：

X-Webhook-Signature: sha256=5a8c7b...

用 HMAC-SHA256 搭配每個 Webhook 訂閱的 secret key 產生簽章。接收方用相同的 key 重新計算，比對一致才處理。

重試機制

Webhook 推送失敗（對方伺服器掛了、回傳非 2xx）時，要有指數退避的重試策略：

第 1 次重試：30 秒後
第 2 次重試：2 分鐘後
第 3 次重試：15 分鐘後
第 4 次重試：1 小時後
第 5 次重試：4 小時後

連續失敗 5 次後暫停該 Webhook 訂閱，並 Email 通知開發者。提供一個「Webhook 記錄」頁面，讓開發者能看到每次推送的 payload 和回應，方便除錯。

Webhook 事件推送機制

速率限制怎麼定？太鬆太緊都不行

速率限制（Rate Limiting）是保護你的伺服器不被打爆的安全閥，也是 API 商業化的基礎。 沒有速率限制，一個寫得不好的第三方爬蟲就能把你整個平台拖慢。

分級策略

不同等級的 API 使用者給不同的額度：

免費方案：30 req/min，日請求上限 1,000 次
標準方案：60 req/min，日上限 10,000 次
進階方案：200 req/min，日上限 100,000 次
企業方案：自訂額度，專屬支援

回應 header 一定要帶速率限制資訊：

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1711526400

超過限制時回傳 429 Too Many Requests，body 裡附上 Retry-After 秒數。

不同端點不同限制

出價 API 要比查詢 API 更嚴格。理由很簡單：有人可能寫機器人大量出價去擾亂市場。建議出價 API 的限制是一般 API 的 1/3 到 1/5，例如一般 API 60 req/min，出價 API 限制 10 req/min。

另外，搜尋 API 通常是最吃資源的端點，也需要獨立的限制。根據實際經驗，搜尋 API 佔整體 API 流量的 40-50%，如果跟其他端點共用額度，會被搜尋吃光。

API 速率限制策略比較

實務案例：某拍賣平台的 API 開放歷程

某台灣二手精品拍賣平台在 2024 年開放 API 後的數據變化很有參考價值：

開放前：月活躍使用者 8 萬，拍品上架全靠後台手動操作
開放後 6 個月：串接 API 的商家 從 0 到 35 家，透過 API 上架的拍品佔比達 62%
第三方工具帶來的流量佔比：18%（主要來自 3 個價格比較網站）
API 呼叫量：日均 12 萬次，其中 70% 是讀取操作

這個案例說明一件事：API 開放不是只有技術工作，更是業務策略。它讓平台從「自己找商家」變成「商家用 API 自助入駐」，營運人力直接省了一半。

API 文件怎麼做才讓開發者愛用？

API 做得再好，沒有好的文件等於不存在。 開發者試用你的 API 時，如果文件不清楚、範例不能跑，90% 的人會在 15 分鐘內放棄。

幾個實務上的重點：

互動式文件

用 Swagger UI 或 Redoc 生成互動式文件，讓開發者直接在瀏覽器裡試打 API。搭配 sandbox 環境，用測試用的 API Key 就能體驗完整流程。

範例程式碼

每個端點至少提供 cURL、JavaScript（fetch）、Python（requests）三種範例。拍賣場景的話，PHP（Laravel HTTP Client）也很重要——台灣很多商家的後台是 PHP 寫的。

快速入門指南

5 分鐘內完成「註冊 → 取得 API Key → 打第一支 API → 拿到拍品列表」。流程越短，開發者留存率越高。

Changelog

每次 API 變更都要公告，破壞性變更提前至少 90 天通知，附上具體遷移步驟。

如果你的平台有多語系需求，API 文件也要考慮國際化——至少提供英文版本，畢竟海外開發者也可能串接你的 API。

拍賣 API 的即時功能：WebSocket 還是 SSE？

出價是即時的，但 REST API 是 request-response 的——這中間的落差需要額外的即時通道來補。 兩個常見的選項：

WebSocket

雙向通訊，適合需要即時互動的場景。在拍賣中，WebSocket 可以用來：

即時推送新出價給正在看該拍品的所有人
即時更新倒數計時器
即時通知防狙擊延時

關於 WebSocket 在拍賣中的深入應用，即時出價 WebSocket 架構有完整的技術分析。

Server-Sent Events（SSE）

單向推送，比 WebSocket 簡單，但只能伺服器推給客戶端。適合只需要接收事件、不需要從客戶端送訊息的第三方工具。

對第三方開發者來說，SSE 的門檻低很多：不需要維護 WebSocket 連線、不需要處理重連邏輯，用一般的 HTTP client 就能接收事件串流。建議 API 同時提供兩種選項，讓開發者自己選適合的。

GraphQL vs REST：拍賣平台該選哪個？

務實的做法：核心 API 用 REST，前端自己的查詢層可以用 GraphQL。REST 簡單直覺、HTTP cache 直接用，拍賣平台 80% 的需求就夠了。對第三方開發者只開放 REST——GraphQL 的 rate limiting 和權限控制比較複雜，學習曲線也高。

如果你正在評估整體技術架構，找一家有 API 開發經驗的網站架設團隊可以幫你少走很多彎路。

常見問題

Q：小平台也需要做 API 嗎？ 需要，但可以分階段。第一階段先做內部 API（前後端分離用），第二階段開放給入駐商家，第三階段才對外開放給第三方開發者。從內部 API 開始做，設計品質通常比較好，因為你自己就是第一個使用者。

Q：API 要收費嗎？ 看策略。免費方案能吸引開發者進來試用，建立生態系。收費方案則是在開發者已經產生依賴後的自然商業模式。建議免費方案的額度要足夠開發者完成 MVP，但不夠用在正式環境——這樣他們會自然升級。

Q：怎麼防止有人用 API 做出價機器人擾亂市場？ 三道防線：速率限制（出價 API 嚴格限制）、行為分析（異常出價模式自動標記）、人工審核（可疑帳號暫停 API 存取）。另外，出價 API 可以加入驗證碼或簽章機制，提高自動化出價的門檻。

Q：API 版本要維護多久？ 舊版本至少維護 6-12 個月。發布新版時同時公告舊版的 Sunset 日期，並在舊版的每個回應 header 加上 Sunset 和 Deprecation 標記。定期統計各版本的流量，當舊版流量低於 5% 時可以考慮正式下線。

Q：開發者文件要用什麼工具做？ OpenAPI（Swagger）規格寫 API 定義，搭配 Redoc 或 Swagger UI 生成互動文件。如果想要更好的開發者體驗，Mintlify 或 ReadMe.io 提供更現代化的文件平台，支援搜尋、版本切換、API Playground 等功能。