API最佳實務

請遵循這些準則來建立與 EC-Permit API 的穩健、高效的整合。

錯誤處理

始終優雅地處理錯誤：

檢查回應狀態代碼

解析回應正文中的錯誤訊息

實現暫時性故障的重試邏輯

記錄錯誤以進行調試

速率限制

遵守速率限制以避免限制：

預設限制：每個 API 金鑰每分鐘 100 個請求

查看

X-RateLimit-剩餘

標頭

實施指數退避

429

回應

盡可能進行批量操作

高效率分頁

對大型資料集使用基於遊標的分頁

僅請求您需要的頁面大小

適當時緩存結果

使用篩選器減小資料集大小

冪等性

使請求安全地可重複：

包括

冪等性金鑰

POST 請求的標頭

使用唯一鍵（建議 UUID）

相同的密鑰在 24 小時內返回相同的結果

安全

保護您的整合：

將 API 金鑰儲存在環境變數中

切勿在錯誤訊息中記錄或公開密鑰

僅使用 HTTPS

驗證 Webhook 簽名

在您的應用程式中實施適當的存取控制

Webhook 最佳實踐

非同步處理 webhook

返回

200

快點，稍後處理

冪等地處理重複交付

監控 webhook 失敗

為禁用的 Webhook 設定警報

API 版本策略

• 在所有請求路徑保留版本前綴（例如 /v1/）。
• 留意回應標頭與發行說明中的棄用提示。
• 先在非正式專案驗證新版本，再切換正式流量。
• 若有官方 SDK，優先採用以內建上述約定。

考慮使用我們的官方 SDK（Node.js、Python），它會自動實現這些最佳實踐。

整合清單

安全儲存的 API 金鑰（環境變數）

已實作錯誤處理

速率限制處理到位

POST 請求的冪等鍵

Webhook 簽章驗證

非同步 Webhook 處理

用於調試的日誌記錄

配置監控和警報

表單類型架構

返回文件主頁