eSIM API チェックリスト (2026): 旅行用 eSIM API に必須の 12 の機能 — および各機能のテスト方法

クイック回答

実用的なトラベル eSIM API には、安全なトークン認証、リトライによる二重課金を防ぐためのべき等性キー（idempotency keys）、価格を固定できる見積もり機能、すべての eSIM イベントに対する署名付き Webhook、eSIM のライフサイクルやエラー、チャージ、使用量データ、一時停止/再開、そしてカバレッジやフェアユースの詳細を含むカタログフィードを備えたサンドボックスが必要です。本番環境に移行する前に、サンドボックスですべての機能をテストしてください。

eSIM API をアプリや旅行プラットフォーム、予約エンジンに接続すること自体は難しくありません。難しいのは、リリースした後に「タイムアウト時に API が二重課金してしまう」「顧客のデータ残量がわからなくなる」「エラーのテスト方法がない」といった事態に気づくことです。

このチェックリストでは、本番環境で重要となる 12 の機能と、契約前にそれらをどのようにテストすべきかをまとめています。ここでは TripoSIM Partner API を例として使用していますが、同じチェックリストを使って他のプロバイダーと比較することもできます。

1. 安全なトークン認証

チェックポイント: OAuth 2.0 クライアント資格情報。クライアント ID とシークレットを、短期間有効なアクセストークンと交換できるか。シークレットがすべてのリクエストに含まれないようになっているか。

テスト方法: トークンをリクエストし、それが期限切れになることを確認します。TripoSIM API では、POST /auth/token を実行すると 15 分間有効なアクセストークンが返されます。コード内で期限が切れる前に自動的にリフレッシュするようにしてください。

2. べき等性キー（二重課金の防止）

チェックポイント: すべての注文とチャージにおいて `Idempotency-Key` ヘッダーがあるか。リクエストがタイムアウトして同じキーでリトライした場合、API が 2 つ目の eSIM を作成するのではなく、元の結果を返すべきです。

テスト方法: 同じキーを使用して同じ注文を 2 回送信し、注文が 1 つだけ作成されることを確認します。次に、同じキーを使用して異なるボディを送信してください。優れた API であれば、それを拒否します。TripoSIM では、本番の注文とチャージにキーを必須としており、異なるリクエストでキーが再利用された場合は 409 IDEMPOTENCY_KEY_REUSED を返します。

3. 価格を固定できる見積もり機能

チェックポイント: 価格を取得し、それを短時間保持できる方法があるか。これにより、顧客には表示された通りの正確な金額を支払ってもらうことができます。

テスト方法: 見積もり（quote）を作成し、少し待ってからその見積もりを使って注文します。TripoSIM の見積もりは 10 分間有効です。期限切れの見積もりには 409 QUOTE_EXPIRED が返されるため、予期せぬ価格を請求する代わりに再見積もりを行うことができます。

4. きれいなカタログフィード

チェックポイント: 価格、データ量、有効期限、対応国、5G、チャージ対応、そして無制限プランの場合は 1 日あたりのフルスピード制限などが記載された、すべてのプランをリストアップできるエンドポイントがあるか。

テスト方法: 特定の国のカタログを取得し、プロバイダー自身のウェブサイトと比較します。TripoSIM の `/catalog` エンドポイントは JSON または CSV を返し、その国をカバーするリージョンプランを含み、無制限プラン用のフェアユースフィールド（fup_daily_mb, fup_throttle_kbps）も追加されます。[無制限の 1 日あたりの制限の仕組み](/blog/unlimited-esim-daily-limit-by-country-2026) を参照してください。

5. 即時の注文と QR コード配信

チェックポイント: 注文レスポンス（または数秒後の Webhook）に、標準的な LPA フォーマット（例: `LPA:1$smdp.example.com$ACTIVATION_CODE`）でアクティベーションコードが含まれているか。これにより、QR コードやワンタップインストールリンクを表示できます。

テスト方法: サンドボックスで注文を行い、LPA 文字列から QR コードを生成し、スマートフォンのカメラでスキャンしてフォーマットが有効であることを確認します。

6. すべてのイベントに対する署名付き Webhook

チェックポイント: eSIM のライフサイクル全体に対するプッシュ通知があり、攻撃者が偽造できないように署名されているか。

TripoSIM は 8 つのイベントタイプを送信します: `order.completed`, `order.failed`, `esim.activated`, `esim.usage_80`, `esim.suspended`, `esim.resumed`, `esim.depleted`, `esim.expired`。各リクエストには、あなたの署名シークレットを使用してタイムスタンプと生ボディの HMAC-SHA256 を計算した `X-TripoSIM-Signature` ヘッダーが含まれます。

<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 を登録し、注文を発生させ、コード内で署名を検証します。次に、ボディの 1 バイトを変更し、検証がそれを拒否することを確認してください。

7. eSIM のライフサイクル全体をシミュレートできるサンドボックス

チェックポイント: 本物の eSIM は、アクティベートしてデータを使用するまでに数日かかることがあります。優れたサンドボックスは、これを早送り（fast-forward）できます。

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 分間キャッシュするため、リアルタイムのアラートには Webhook (`esim.usage_80`, `esim.depleted`) を使用してください。

11. 一時停止と再開

チェックポイント: eSIM を一時停止する方法（例：支払いに異議が申し立てられた場合や、顧客から紛失の報告があった場合）と、後で再開する方法があるか。

テスト方法: サンドボックスの eSIM を一時停止し、`esim.suspended` Webhook が届くことを確認します。その後、再開して `esim.resumed` を確認します。

12. 明確なレート制限、エラーコード、および変更履歴

チェックポイント: ドキュメント化された制限、リトライすべきかどうかを教えてくれるエラーコード、およびアップデートに驚かないための公開された変更履歴（changelog）があるか。

テスト方法: エラーリストを読み、各コードをコード内で「リトライする」または「リトライしない」にマッピングします。TripoSIM では、パートナーアカウントごとに 1 分間に 120 リクエストを許可しており（個別の API キーに対してより低い制限を設定することも可能です）、429 レスポンスでは `Retry-After` ヘッダーを返し、すべてのエラーコードにリトライ可能かどうかを明記し、変更履歴エンドポイントを公開しています。

シンプルなローンチ計画

1日目: サンドボックスキーを取得し、認証を行い、カタログを取得する。
2日目: べき等性キーを使用してサンドボックスで注文を行い、QR コードを表示する。
3日目: Webhook を追加し、ライフサイクルとエラーのシミュレーターを実行する。
4日目: チャージと使用量機能を追加し、本物の iPhone や Android で 1 つのライブ eSIM を使ってテストする。
5日目: 本番稼働。

ほとんどのチームは 1 週間以内に接続を完了します。詳細な [API ドキュメント](https://docs.triposim.com) を読むか、ステップバイステップの [eSIM API 統合ガイド](/blog/esim-reseller-api-how-to-integrate-travel-esim-sales-into-your-platform) を参照してください。

よくある質問

トラベル eSIM API には何が含まれるべきですか？

最低限必要なもの：トークン認証、べき等性キー、価格見積もり、カタログフィード、即時の QR/アクティベーションコード、署名付き Webhook、ライフサイクルとエラーシミュレーターを備えたサンドボックス、チャージ、使用量データ、一時停止/再開、およびドキュメント化されたレート制限とエラーコードです。

なぜ eSIM API にとってべき等性キーが重要なのですか？

すべての eSIM 注文には実際のお金がかかります。リクエストがタイムアウトしてシステムがリトライした場合、べき等性キーがあれば、2 つ目の eSIM を購入するのではなく、最初の結果が返されることが保証されます。

eSIM を購入せずに eSIM API をテストするにはどうすればよいですか？

サンドボックスを使用してください。優れたサンドボックスは、財布からお金を引くことなく、注文、アクティベーション、データ使用、枯渇、期限切れをシミュレートし、エラーを強制することもできます。

eSIM API の統合にはどのくらいの時間がかかりますか？

ドキュメントが充実した API と完全なサンドボックスがあれば、ほとんどのチームは 3〜5 営業日で本番稼働できます。

TripoSIM API はホワイトラベル配信をサポートしていますか？

はい。アクティベーションコードと QR データを受け取ることができるため、独自のブランドで自社アプリやメール内で eSIM を提供できます。[API プログラム](/api-program) を参照してください。

まとめ

価格は重要ですが、eSIM API における真の違いはリリース後に現れます。二重課金をしないリトライ、信頼できる Webhook、そして事前にすべてをテストできるサンドボックスです。契約する前に、どのプロバイダーに対してもこのチェックリストを実行してください。まずは [私たちのサンドボックスから始めて](/api-program)、TripoSIM Partner API がどのようなスコアを出せるか確認してみてください。