eSIM API 檢查清單 (2026)：旅遊 eSIM API 必須具備的 12 項功能 — 以及如何測試每一項

Q: TripoSIM API 支持白標 (white-label) 交付嗎？

是的。您可以接收激活碼和 QR 數據，因此可以在您自己的應用程式或電子郵件中，以您自己的品牌交付 eSIM。請參閱 API 計畫。

快速回答

一個可投入生產環境的旅遊 eSIM API 應該提供安全的 token 認證、確保重試不會導致重複扣款的冪等性金鑰 (idempotency keys)、可以鎖定價格的報價功能、針對每個 eSIM 事件的已簽署 Webhooks、一個可以模擬完整 eSIM 生命週期與錯誤的沙盒環境 (sandbox)、儲值功能、用量數據、暫停/恢復功能，以及包含覆蓋範圍與公平使用原則細節的產品目錄。在正式上線前，請務必在沙盒中測試每一項功能。

將 eSIM API 對接到您的應用程式、旅遊平台或預訂引擎並不難。困難的地方在於，在上線後才發現 API 在逾時時會重複扣款、無法告知客戶何時用完流量，或者完全沒有測試失敗情境的方法。

這份檢查清單涵蓋了在生產環境中至關重要的 12 項功能，並針對每一項說明在簽約前該如何測試。我們以 TripoSIM Partner API 作為範例，但您也可以使用相同的清單來比較任何供應商。

1. 安全的 token 認證

要尋找什麼： OAuth 2.0 客戶端憑證 (client credentials)：您透過交換 client ID 和 secret 來換取短暫有效的 access token。Secret 不會隨每次請求傳輸。

如何測試： 請求一個 token，然後檢查它是否會過期。在 TripoSIM API 中，POST /auth/token 會返回一個有效期為 15 分utes 的 access token。請確保您的程式碼會在它過期前自動進行刷新。

2. 冪等性金鑰 (避免重複扣款)

要尋找什麼： 在每個訂單和儲值請求中都有一個 Idempotency-Key 標頭。如果您的請求逾時且您使用相同的金鑰進行重試，API 必須返回原始結果，而不是創建第二個已付款的 eSIM。

如何測試： 使用相同的金鑰發送兩次相同的訂單，並確認您只收到一個訂單。接著使用相同的金鑰但發送不同的內容 —— 一個好的 API 會拒絕該請求。TripoSIM 要求在生產環境的訂單和儲值中使用金鑰，如果使用相同的金鑰發送不同的請求，會返回 409 IDEMPOTENCY_KEY_REUSED。

3. 可鎖定價格的報價功能

要尋找什麼： 一種可以獲取價格並在短時間內保持該價格的方法，以便您的客戶支付的金額與您展示的完全一致。

如何測試： 創建一個報價，等待一段時間，然後使用該報價進行訂單。TripoSIM 的報價有效期為 10 分鐘；過期的報價會返回 409 QUOTE_EXPIRED，讓您可以重新報價，而不是向客戶收取意外的價格。

4. 清晰的產品目錄

要尋找什麼： 一個可以列出所有方案的端點 (endpoint)，包含價格、流量、有效期、覆蓋國家、5G 支持、儲值支持 —— 以及針對無限流量方案的每日全速限制。

如何測試： 抓取一個國家的目錄，並與供應商自己的網站進行比較。TripoSIM 的 /catalog 端點返回 JSON 或 CSV，包含覆蓋該國的區域方案，並為無限流量方案添加了公平使用欄位 (fup_daily_mb, fup_throttle_kbps)。請參閱[無限每日流量限制如何運作](/blog/unlimited-esim-daily-limit-by-country-2026)。

5. 即時訂單與 QR 碼交付

要尋找什麼： 訂單回應（或幾秒後的 webhook）應包含標準 LPA 格式的激活碼，例如 `LPA:1$smdp.example.com$ACTIVATION_CODE`，以便您可以顯示 QR 碼或一鍵安裝連結。

如何測試： 下一個沙盒訂單，從 LPA 字串生成 QR 碼，並使用手機相機掃描以檢查格式是否有效。

6. 針對每個事件的已簽署 Webhooks

要尋找什麼： 針對整個 eSIM 生命週期的推送通知，且經過簽署以防止攻擊者偽造。

TripoSIM 發送八種事件類型：order.completed, order.failed, esim.activated, esim.usage_80, esim.suspended, esim.resumed, esim.depleted 以及 esim.expired。每個請求都帶有一個 X-TripoSIM-Signature 標頭 —— 這是使用您的簽署金鑰對時間戳和原始主體進行 HMAC-SHA256 加密後的結果：

<pre><code>// reject requests older than 5 minutes (replay protection) if (Math.floor(Date.now() / 1000) - parseInt(timestamp) > 300) throw new Error('Webhook too old'); const expected = crypto .createHmac('sha256', signingSecret) .update(timestamp + '.' + rawBody) .digest('hex'); if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) { throw new Error('Invalid webhook signature'); }</code></pre>

如何測試： 註冊一個 webhook，觸發一個訂單，並在您的程式碼中驗證簽名。接著修改主體中的一個位元組 (byte)，並確保您的檢查機制會拒絕它。

7. 能模擬整個 eSIM 生命週期的沙盒

要尋找什麼： 真實的 eSIM 需要數天才能激活並使用數據。一個好的沙盒可以讓您「快進」。

Ready to get connected?

Get a travel eSIM for 200+ destinations — instant QR by email, no roaming charges, with a discount applied automatically at checkout.

Browse eSIM plans

如何測試： 在 TripoSIM 沙盒中，使用 POST /sandbox/esims/{iccid}/simulate 並帶上 activate, usage, deplete, expire 或 reset 等動作。每個步驟都會觸發對應的 webhook，因此您可以在幾分鐘內測試您的「流量即將用盡」郵件，而不是等待數天。

8. 錯誤模擬

要尋找什麼： 一種可以故意強制產生錯誤的方法，以便您知道您的應用程式如何處理這些錯誤。

如何測試： 發送帶有 insufficient_balance, price_changed, rate_limit, provider_unavailable 或 timeout 等模式的 X-Sandbox-Simulate 標頭，並檢查您的應用程式是否顯示清晰的訊息，且僅在應該重試時才進行重試。

9. 同一張 eSIM 的儲值功能

要尋找什麼： 流量用盡的客戶應該能夠直接增加流量，而無需安裝新的 eSIM。

如何測試： 在沙盒中調用 POST /esims/{iccid}/topup（使用冪等性金鑰），然後檢查新的流量餘額。同時檢查哪些方案支持儲值 —— 目錄應該會告訴您。

10. 用量與狀態數據

要尋找什麼： 一個可以查詢已用流量、剩餘流量和到期日期的端點，以便您的客服團隊和應用程式可以回答「我還剩多少流量？」

如何測試： 在模擬用量事件後，調用 GET /esims/{iccid}/usage。TripoSIM 會快取用量數據 5 分鐘，因此請使用 webhooks (esim.usage_80, esim.depleted) 來獲取即時警報。

11. 暫停與恢復

要尋找什麼： 一種暫停 eSIM 的方法 —— 例如在付款發生爭議或客戶報告手機遺失時 —— 並在稍後恢復它。

如何測試： 暫停一個沙盒 eSIM，確認收到 esim.suspended webhook，然後恢復它並確認收到 esim.resumed。

12. 明確的速率限制、錯誤代碼與更新日誌

要尋找什麼： 文檔化的限制、能告知您是否可以重試的錯誤代碼，以及公開的更新日誌 (changelog)，確保更新不會讓您感到意外。

如何測試： 閱讀錯誤列表，並在您的程式碼中將每個代碼映射為「重試」或「不要重試」。TripoSIM 允許每個合作夥伴帳戶每分鐘進行 120 次請求（您可以為個別 API 金鑰設置較低的限制），在返回 429 響應時會帶有 Retry-After 標頭，將每個錯誤代碼標記為可重試或不可重試，並提供更新日誌端點。

簡單的上線計劃

第 1 天： 獲取沙盒金鑰、進行認證、抓取產品目錄。
第 2 天： 使用冪等性金鑰下達沙盒訂單並顯示 QR 碼。
第 3 天： 添加 webhooks，運行生命週期與錯誤模擬器。
第 4 天： 添加儲值與用量功能，然後使用一張真實的 eSIM 在手機上進行測試。
第 5 天： 正式上線。

大多數團隊在不到一週的時間內就能完成對接。請閱讀完整的 [API 文檔](https://docs.triposim.com) 或參閱我們的逐步 [eSIM API 對接指南](/blog/esim-reseller-api-how-to-integrate-travel-esim-sales-into-your-platform)。

常見問題

旅遊 eSIM API 應該包含哪些功能？

至少應包含：token 認證、冪等性金鑰、價格報價、產品目錄、即時 QR/激活碼、已簽署 Webhooks、具備生命週期與錯誤模擬功能的沙盒、儲值功能、用量數據、暫停/恢復功能，以及文檔化的速率限制與錯誤代碼。

為什麼冪等性金鑰對 eSIM API 很重要？

每張 eSIM 訂單都涉及真實的金錢。如果請求逾時且您的系統進行重試，冪等性金鑰可以確保重試返回的是第一次的結果，而不是購買第二張 eSIM。

我如何在不購買 eSIM 的情況下測試 eSIM API？

使用沙盒。一個好的沙盒可以模擬訂單、激活、數據使用、用盡與過期 —— 並允許您強制產生錯誤 —— 而不會扣除您的錢包費用。

eSIM API 對接需要多長時間？

有了文檔齊全的 API 和功能完整的沙盒，大多數團隊可以在 3–5 個工作日內完成上線。

TripoSIM API 支持白標 (white-label) 交付嗎？

是的。您可以接收激活碼和 QR 數據，因此可以在您自己的應用程式或電子郵件中，以您自己的品牌交付 eSIM。請參閱 [API 計畫](/api-program)。

總結

價格固然重要，但對於 eSIM API 來說，真正的差異在於上線之後：永不重複扣款的重試機制、您可以信任的 webhooks，以及一個讓您能先測試一切的沙盒。在您決定使用任何供應商之前，請用這份清單進行測試 —— 並可以[從我們的沙盒開始](/api-program)，看看 TripoSIM Partner API 的表現如何。