開発者
エンドポイント4つ、webhook2つ、意外な落とし穴はなし。
ストアにできることは、あなたのプロダクトにもできます。全機能が1ページに収まります。
この API がある理由
通信の用意は、旅行者が予約したその瞬間に、あなたのプロダクトの中で済むべきです。空港で初めて気づくようなものであってはいけません。
予約プラットフォームなら旅程にデータを付けられます。端末メーカーなら初期設定中にプランを有効化できます。社内ツールなら、新しく入った人にノートパソコンと一緒に通信量を渡せます。
この3つはどれも、4回の呼び出しと1つの webhook で済みます。ログインするパートナーポータルもなく、アップロードする CSV もありません。
認証
すべてのリクエストで、キーをベアラートークンとして送ってください。キーの接頭辞はサンドボックスが sk_test、本番が sk_live です。
環境を取り違えて貼り付けたキーは、黙って課金するのではなく 401 で失敗します。キーには権限の範囲があるので、読み取り専用キーでは注文できませんし、あるチーム用に発行したキーから別のチームは見えません。
ローテーションはコンソールからいつでもできます。古いキーは24時間動き続けるので、一斉切り替えの日を迫られることはありません。
curl https://api.orbislo.com/v1/catalog?country=jp \
-H "Authorization: Bearer sk_live_9f2c..." \
-H "Orbislo-Version: 2026-08-01"バージョンヘッダーについて
バージョンヘッダーは任意で、レスポンスの形を日付付きのリリースに固定します。指定しない場合は、キーを作成した時点のバージョンが使われ、それが勝手に変わることはありません。
フィールドの追加は予告なく行います。フィールドの削除や型の変更を、同じバージョンの中で行うことはありません。
4
API 全体のエンドポイント数。ほかに webhook イベントが2つ
90秒
注文成立からプロファイル有効化までの中央値
24時間
同じ冪等キーの再送に元のレスポンスを返す期間
エンドポイント一覧
| メソッド | パス | 何をするか | 流量制限 |
|---|---|---|---|
| GET | /v1/catalog | 販売中の全プラン。価格、データ量、有効期間、対象国を含みます。 | 毎分600 |
| POST | /v1/orders | プランを購入し、プロビジョニングのジョブが付いた注文を返します。 | 毎分60 |
| GET | /v1/provisioning/:id | 1件のプロビジョニングのジョブの状態。queued から activated または failed まで。 | 毎分600 |
| GET | /v1/usage/:esim_id | 使用済みバイト数、残りバイト数、その eSIM が接続しているキャリア。 | 毎分300 |
制限はキーごとのスライディングウィンドウです。すべてのレスポンスに残り回数とリセット時刻が入り、429 には再試行までの秒数が入ります。用途として本当に大きな枠が必要なら、言ってください。枠を広げるのは設定変更であって交渉事ではありません。
カタログ
何があっていくらなのか、その正解はカタログです。現在稼働している145の渡航先をすべて含みます。
国、地域、プランの系統で絞り込めます。価格は最小通貨単位で返るので、浮動小数点があなたの課金コードに届くことはありません。
GET /v1/catalog?country=jp
{
"object": "list",
"data": [
{
"id": "plan_jp_5gb",
"name": "Japan 5 GB",
"countries": ["jp"],
"data_mb": 5120,
"price": { "amount": 1150, "currency": "usd" },
"expires": false,
"throttle_mbps": null,
"tethering": true,
"carriers": ["NTT Docomo", "KDDI", "SoftBank"]
}
],
"has_more": false
}二度読む価値のある2つのフィールド
expires フィールドは、当社が販売する従量制プランではすべて false です。当社のデータは失効しないからです。価格比較を作っているなら、このフィールドは価格そのものよりも計算を大きく変えます。
throttle_mbps フィールドは従量制プランでは null、無制限デイパスでは 1 です。デイパスは1日 2 GB までがフル速度で、その後は 1 Mbps に下がります。
この制限値を API に入れているのは、購入ボタンに印字しているのと同じ理由です。旅行者が後から知る数字は、そのままサポートへの問い合わせになります。
注文
POST 1回でプランを購入し、プロビジョニングが始まります。Idempotency-Key ヘッダーは推奨ではなく必須です。
この API で最悪の結末は、旅行者に課金されたかどうか分からないまま終わるタイムアウトです。キーを必須にすれば、その状態そのものがなくなります。
POST /v1/orders
Idempotency-Key: 4f1d0f6e-1c3a-4a2b-9d77-1b6a0e7c9f21
Content-Type: application/json
{
"plan_id": "plan_jp_5gb",
"traveller_ref": "user_88213",
"imei": "356938035643809",
"activate": "on_first_use"
}
201 Created
{
"id": "ord_7Kd2mQ",
"status": "provisioning",
"esim_id": "esim_2xB9Ln",
"provisioning_id": "prv_5Ttq81",
"amount": { "amount": 1150, "currency": "usd" },
"activation": {
"type": "universal_link",
"url": "https://orbislo.com/i/2xB9Ln",
"lpa": "LPA:1$rsp.orbislo.com$K4-9TT-2XB9LN"
}
}端末チェックと遅延アクティベーション
imei フィールドは任意ですが、強くお勧めします。送ってもらえれば、課金の前に eSIM 対応とキャリアロックを確認します。
プロファイルを保持できない端末には、プランを売って旅行者を怒らせる代わりに、device_not_eligible を伴う 422 が返ります。
activate を on_first_use にすると、有効期間はあなたのサーバーが呼び出した時点ではなく、旅行者が現地に着いた時点から始まります。
プロビジョニングの状態
相手側にキャリアのプラットフォームがあるため、プロビジョニングは非同期です。このエンドポイントを問い合わせるか、webhook を受け取って問い合わせ自体をやめてください。
queued から activated までの中央値は90秒未満です。10分たっても queued のままなら失敗であり、自動で返金されます。
GET /v1/provisioning/prv_5Ttq81
{
"id": "prv_5Ttq81",
"status": "activated",
"states": [
{ "state": "queued", "at": "2026-08-24T09:14:02Z" },
{ "state": "provisioning", "at": "2026-08-24T09:14:04Z" },
{ "state": "installed", "at": "2026-08-24T09:14:41Z" },
{ "state": "activated", "at": "2026-08-24T09:15:07Z" }
],
"carrier": "KDDI",
"failure_reason": null
}Webhook
イベントは2つで、どちらも旅行者に伝えるべき内容を変えます。任意の HTTPS エンドポイントに向けられ、環境ごとに別々に設定します。
Webhook のイベント
| イベント | 発火する条件 | 受け取ったらどうするか |
|---|---|---|
| esim.activated | プロファイルが初めてネットワークに接続したとき。 | つながったことを旅行者に伝えてください。購入が本人にとって現実になる瞬間です。 |
| esim.depleted | 使用量がしきい値を越えたとき。80パーセントで1回、100パーセントでもう1回。 | 困り果てた後ではなく、その前にチャージを提案してください。 |
POST https://your-app.example/hooks/orbislo
Orbislo-Signature: t=1756032907,v1=6c1b...
Content-Type: application/json
{
"id": "evt_9pQ4rz",
"type": "esim.depleted",
"created": "2026-08-24T11:41:33Z",
"data": {
"esim_id": "esim_2xB9Ln",
"threshold": 80,
"used_mb": 4096,
"remaining_mb": 1024,
"country": "jp"
}
}配信の検証
タイムスタンプ、ピリオド、リクエストの生のボディをつなげ、エンドポイントのシークレットで HMAC SHA-256 を計算します。比較は定数時間で行ってください。
タイムスタンプが5分より古いものは拒否してください。これでリプレイを防げます。配信は最低1回で、24時間のあいだに8回まで再送されるため、ハンドラーはイベント ID で重複を判定してください。
エラーコード
| HTTP | コード | 意味 | 対処 |
|---|---|---|---|
| 400 | invalid_request | フィールドが足りないか、型が違います。ボディに該当フィールド名が入ります。 | リクエストを直してください。再試行しても解決しません。 |
| 401 | invalid_token | ベアラートークンが誤りか、失効済みか、別環境のものです。 | サンドボックスのキーを本番ホストに送っていないか確認してください。 |
| 402 | insufficient_balance | アカウント残高が注文額に足りません。 | チャージしてから、同じ冪等キーで再試行してください。 |
| 404 | not_found | この環境にはその ID のオブジェクトがありません。 | サンドボックスの ID と本番の ID は互換ではありません。 |
| 409 | idempotency_conflict | 同じ冪等キーが別のボディで再利用されました。 | 新しいキーを使うか、元のボディをバイト単位でそのまま送り直してください。 |
| 422 | device_not_eligible | 端末が eSIM 非対応か、キャリアロックがかかっています。 | 課金する前に端末チェックを実行してください。 |
| 429 | rate_limited | そのエンドポイントの枠を越えました。 | ヘッダーの再試行秒数に従って待ってください。連続で叩かないでください。 |
| 500 | internal_error | 当社側の問題です。すでにアラートが上がっています。 | 2秒後に同じ冪等キーで再試行してください。 |
| 503 | provider_unavailable | 上流のキャリアのプラットフォームが停止しています。 | 最大10分まで再試行してください。第2のキャリアがある地域では自動で切り替えます。 |
すべてのエラーのボディに、コード、人間が読めるメッセージ、リクエスト ID が入ります。サポートにリクエスト ID を伝えれば、最初の4つの質問を飛ばせます。
サンドボックスと本番の違い
ホストもパスもレスポンスの形も同じです。接頭辞 sk_test のキーはお金に触れませんし、キャリアのプロファイルも作りません。
プロビジョニングのジョブは状態遷移をすべて4秒ほどで通過するので、テストが1件ごとに90秒待つことはありません。
プラン ID の plan_test_fail を注文すると、理由付きの失敗ジョブになります。plan_test_slow を注文すると、provisioning のまま11分とどまるので、タイムアウトの経路を試せます。
webhook の配信はサンドボックスでも発生し、環境ごとに設定した URL に届きます。
何も作りたくない場合
アフィリエイトなら、実装ゼロで紹介した注文に応じて報酬が出ます。多くのコンテンツサイトにはこれが正解です。
MCP エンドポイントは、設定1行とコードなしで、当社の通信エリアのデータセットと価格インデックスを AI アシスタントに公開します。
あなたが売ることになるプラン、カタログの裏にある実測速度データ、国の全リストは、すべてこのサイトで公開しています。