旅行会社・OTA・リセラー向けのeSIM API

1つの国のパッケージから始め、旅行者向けに1つ注文して、その注文のセットアップデータを読み取ります。Sandboxではダミーのアクティベーションコードを持つテスト用eSIMが作成され、引き落としは行われません。コンソールには、カタログのレスポンスを抜粋したものが表示されます。

1. パッケージを一覧取得

   カタログの呼び出しはcountryとtypeを受け取り、条件に合うパッケージを、旅行会社の通貨建ての価格で返します。旅行者が選んだパッケージのpackage_idを保存してください。

   curl 'https://api.fx-port.com/api/v1/esims/packages?country=france&type=local' \
     -H "Authorization: Bearer fxp_test_YOUR_KEY"

   200 OK
   Content-Type: application/json
   Cache-Control: private, no-store
   X-Environment: sandbox
   ratelimit-limit: 6000
   ratelimit-policy: 6000;w=60
   
   {
     "environment": "sandbox",
     "success": true,
     "endpoint": "/packages",
     "data": [
       {
         "id": "france-in-7days-1gb",
         "package_id": "france-in-7days-1gb",
         "type": "sim",
         "price": 402.5,
         "base_price": 402.5,
         "amount": 1024,
         "day": 7,
         "is_unlimited": false,
         "title": "1 GB - 7 days",
         "is_fair_usage_policy": false,
         "fair_usage_policy": null,
         "data": "1 GB",
         "voice": null,
         "text": null,
         "country_name": "France",
         "country_code": "FR",
         "country_slug": "france",
         // ...
         "operator_name": "KPN France Data only",
         "operator_id": 1704,
         // ...
         "operator_type": "local",
         "operator_is_prepaid": false,
         "operator_esim_type": "Prepaid",
         "operator_warning": null,
         "operator_apn_type": "automatic",
         "operator_is_roaming": true,
         // ...
         "operator_plan_type": "data",
         "operator_activation_policy": "first-usage",
         "operator_is_kyc_verify": false,
         "operator_rechargeability": true,
         // ...
         // ... 1 more
         // ...
         "is_regional": false,
         // ... 10 more
       },
       // ...
     ],
     "meta": {
       "total_packages": 12,
       "filters_applied": {
         // ... 2 more
       },
       "locale": "en",
       "agency_currency": "DZD",
       "currency": "DZD",
       "supplier_currency": "USD",
       "exchange_rate": 250,
       "commission_percentage": "12 %",
       "commission_rate": 12
     }
   }

   表示用に例を省略しています

   • PASS ステータスコードが 200
   • PASS $.success が true と等しい
   • PASS $.data[0].package_id が存在する
   • PASS $.data[0].balance_debit_amount が存在する

   ドキュメントの GET /esims/packages リファレンス

2. eSIMを注文

   注文の作成には、package_idに旅行者のメールアドレスと電話番号を添えます。レスポンスのbooking_idとdata.iccidを保存してください。Sandboxでは、balanceDebited、transactionCreated、payoutCreatedはすべてfalseです。

   curl https://api.fx-port.com/api/v1/esims/orders \
     -H "Authorization: Bearer fxp_test_YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{
     "package_id": "france-in-7days-1gb",
     "first_name": "John",
     "last_name": "Smith",
     "email": "[email protected]",
     "phone": "+15555550123",
     "description": "Order for John Smith"
   }'

   200 OK
   Content-Type: application/json
   Cache-Control: private, no-store
   X-Environment: sandbox
   ratelimit-limit: 1200
   ratelimit-policy: 1200;w=60
   x-fx-limit-class: booking
   
   {
     "environment": "sandbox",
     "success": true,
     "data": {
       "order": {
         "code": "20261101-106852",
         "order_id": "20261101-106852",
         "package_id": "france-in-7days-1gb",
         "type": "sim",
         "description": "Order for John Smith",
         "esim_type": "local",
         "created_at": "2026-11-09 15:23:22",
         "package": "KPN France Data only-1 GB - 7 days",
         "data": "1 GB",
         "validity": 7,
         "price": 468.84,
         "currency": "DZD",
         "total_price": 468.84,
         "retail_price": 468.84,
         "agency_currency": "DZD",
         "supplier_currency": "USD",
         "exchange_rate": 250,
         "voice": null,
         "text": null,
         "coverage": ""
       },
       "sim": {
         "iccid": "8900000540463077957",
         "created_at": "2026-11-09 15:23:22",
         "lpa": "lpa.airalo.com",
         "imsis": null,
         "qrcode": "LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741",
         // ...
         "direct_apple_installation_url": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741",
         "apn_type": "automatic",
         "apn_value": "N/A",
         "apn": {
           // ... 2 more
         },
         "is_roaming": true,
         "confirmation_code": null,
         "msisdn": null,
         "sharing": {
           "access_code": 8803,
           "link": "https://esims.cloud/v8hy7-usgkq6wg"
         }
       },
       "iccid": "8900000540463077957"
     },
     "booking_id": "FX-1793546602916",
     "message": "eSIM order placed successfully",
     "balanceDebited": false,
     "balance_debited": false,
     "transactionCreated": false,
     "transaction_created": false,
     "payoutCreated": false,
     "payout_created": false
   }

   表示用に例を省略しています

   • PASS ステータスコードが 200
   • PASS $.environment が sandbox と等しい
   • PASS $.balance_debited が false と等しい
   • PASS $.data.iccid が存在する

   ドキュメントの POST /esims/orders リファレンス

3. セットアップデータを読む

   セットアップデータの取得はbooking_idを受け取り、注文のQRコード、アクティベーションデータ、インストールリンク、インストール手順を返します。eSIMを所有する旅行者にのみ表示してください。

   curl https://api.fx-port.com/api/v1/esims/bookings/FX-1793546602916/setup-instructions \
     -H "Authorization: Bearer fxp_test_YOUR_KEY"

   200 OK
   Content-Type: application/json
   Cache-Control: private, no-store
   X-Environment: sandbox
   ratelimit-limit: 6000
   ratelimit-policy: 6000;w=60
   
   {
     "environment": "sandbox",
     "success": true,
     "data": {
       "code": "20261101-106852",
       "order_id": "20261101-106852",
       "currency": "DZD",
       "package_id": "france-in-7days-1gb",
       "quantity": 1,
       "type": "sim",
       "description": "Order for John Smith",
       "esim_type": "local",
       "validity": 7,
       "package": "KPN France Data only-1 GB - 7 days",
       "data": "1 GB",
       "price": 468.84,
       "created_at": "2026-11-09 15:23:22",
       // ...
       "installation_guides": {
         "en": "https://www.airalo.com/help/getting-started-with-airalo"
       },
       "text": null,
       "voice": null,
       "sims": [
         {
           "created_at": "2026-11-09 15:23:22",
           "iccid": "8900000540463077957",
           "lpa": "lpa.airalo.com",
           "imsis": null,
           "qrcode": "LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741",
           // ...
           "apn_type": "automatic",
           "apn_value": "N/A",
           "is_roaming": true,
           "confirmation_code": null,
           "apn": {
             "ios": {
               "apn_type": "automatic",
               "apn_value": "N/A"
             },
             "android": {
               "apn_type": "automatic",
               "apn_value": "N/A"
             }
           },
           "msisdn": null,
           "direct_apple_installation_url": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741",
           "direct_android_installation_url": "https://esimsetup.android.com/esim_qrcode_provisioning?carddata=LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741",
           "sharing": {
             "access_code": 8803,
             "link": "https://esims.cloud/v8hy7-usgkq6wg"
           }
         }
       ],
       "total_price": 468.84,
       "retail_price": 468.84,
       "agency_currency": "DZD"
     }
   }

   表示用に例を省略しています

   • PASS ステータスコードが 200
   • PASS $.data.package_id が france-in-7days-1gb と等しい
   • PASS $.data.sims[0].iccid が存在する

   ドキュメントの GET /esims/bookings/{booking_id}/setup-instructions リファレンス

旅行者がeSIMを持った後は、残りのデータ量を読み取り、そのeSIMに追加できるパッケージを確認して、チャージを作成します。利用量はキャッシュされるため、値が数分前のものであることがあります。チャージ履歴は、サイドバーとトランスクリプトにあります。

1. 利用量を読む

   利用量の呼び出しは注文のICCIDを受け取り、メガバイト単位のremainingとtotal、status、有効期限を返します。レスポンスはキャッシュから返され、force=trueでサプライヤーに再確認できます。

   curl https://api.fx-port.com/api/v1/esims/usage/8900000540463077957 \
     -H "Authorization: Bearer fxp_test_YOUR_KEY"

   200 OK
   
   {
     "environment": "sandbox",
     "success": true,
     "data": {
       "data": {
         "remaining": 1024,
         "total": 1024,
         "expired_at": "2026-11-16 15:23:29",
         "is_unlimited": false,
         "status": "ACTIVE",
         "remaining_voice": 0,
         "remaining_text": 0,
         "total_voice": 0,
         "total_text": 0
       },
       "meta": {
         "message": "success"
       }
     }
   }

   • PASS ステータスコードが 200
   • PASS $.data.data.status が ACTIVE と等しい
   • PASS $.data.data.remaining が存在する

   ドキュメントの GET /esims/usage/{iccid} リファレンス

2. チャージ用パッケージを一覧取得

   この呼び出しは、現時点でこのeSIMに追加できるパッケージを一覧で返します。一覧が空の場合、そのeSIMは現在チャージできません。チャージ用のpackage_idは、元の注文ではなく、必ずこの一覧から取得してください。

   curl https://api.fx-port.com/api/v1/esims/topup-packages/8900000540463077957 \
     -H "Authorization: Bearer fxp_test_YOUR_KEY"

   200 OK
   
   {
     "environment": "sandbox",
     "success": true,
     "data": {
       "data": [
         {
           "id": "france-in-7days-1gb-topup",
           "package_id": "france-in-7days-1gb-topup",
           "type": "topup",
           "price": 468.84,
           "amount": 1024,
           "day": 7,
           "is_unlimited": false,
           "title": "1 GB - 7 days",
           "data": "1 GB",
           "short_info": null,
           // ... 12 more
         },
         {
           // ... 22 more
         }
       ]
     }
   }

   表示用に例を省略しています

   • PASS ステータスコードが 200
   • PASS $.data.data の要素数が 2件
   • PASS $.data.data[0].type が topup と等しい

   ドキュメントの GET /esims/topup-packages/{iccid} リファレンス

3. チャージを作成

   チャージの作成には、この一覧のpackage_idとICCIDを指定します。Liveでは、サプライヤーが受け付けた後にのみ残高から引き落とされます。Sandboxではレスポンスのbalanceがゼロで、引き落としは行われません。

   curl https://api.fx-port.com/api/v1/esims/topups \
     -H "Authorization: Bearer fxp_test_YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{
     "package_id": "france-in-7days-1gb-topup",
     "iccid": "8900000540463077957",
     "first_name": "John",
     "last_name": "Smith",
     "email": "[email protected]",
     "phone": "+15555550123"
   }'

   200 OK
   
   {
     "environment": "sandbox",
     "success": true,
     "data": {
       "topup": {
         "code": "20261101-106853",
         "order_id": "20261101-106853",
         "package_id": "france-in-7days-1gb-topup",
         // ... 10 more
       },
       "iccid": "8900000540463077957",
       "balance": {
         // ... 3 more
       }
     },
     "booking_id": "FX-1793546625391",
     "message": "eSIM topup completed successfully",
     "balanceDebited": false,
     "balance_debited": false,
     "transactionCreated": false,
     "transaction_created": false,
     "payoutCreated": false,
     "payout_created": false
   }

   • PASS ステータスコードが 200
   • PASS $.environment が sandbox と等しい
   • PASS $.balance_debited が false と等しい
   • PASS $.data.balance.current が 0 と等しい

   ドキュメントの POST /esims/topups リファレンス

4. チャージ履歴を読む

   チャージ履歴は、1つのeSIMのチャージを新しい順に返します。チャージは予約一覧に含まれないため、ここで確認します。

   curl https://api.fx-port.com/api/v1/esims/bookings/8900000540463077957/topup-history \
     -H "Authorization: Bearer fxp_test_YOUR_KEY"

   200 OK
   
   {
     "environment": "sandbox",
     "success": true,
     "data": [
       {
         "id": "bd6ff7d7-392f-4d56-8dea-4f0f3dff0af9",
         "booking_id": "FX-1793546625391",
         "order_id": "20261101-106853",
         "status": "confirmed",
         "currency": "DZD",
         "total_price": 468.84,
         "agency_commission": 50.24,
         "type": "topup",
         "package_name": "1 GB - 7 days",
         "iccid": "8900000540463077957",
         "customer_email": "[email protected]",
         "customer_first_name": "John",
         "customer_last_name": "Smith",
         "customer_phone": "+15555550123",
         "provider_name": "Airalo",
         // ... 4 more
       }
     ]
   }

   • PASS ステータスコードが 200
   • PASS $.data[0].type が topup と等しい

   ドキュメントの GET /esims/bookings/{iccid}/topup-history リファレンス

販売の前に、旅行者のスマートフォンがeSIMに対応しているかを確認します。販売の後は、予約を読み取り、予約の参照番号が自社のものかを確認します。一括の利用量は、サイドバーに表示されます。

1. デバイス一覧を確認

   対応デバイスの呼び出しは、eSIMに対応していることが確認されているデバイスを、brand、model、osとともに返します。販売の前に、旅行者のスマートフォンを検索してください。

   curl https://api.fx-port.com/api/v1/esims/compatible-devices \
     -H "Authorization: Bearer fxp_test_YOUR_KEY"

   200 OK
   
   {
     "environment": "sandbox",
     "success": true,
     "data": [
       {
         "model": "T803D",
         "os": "android",
         "brand": "Alcatel",
         "name": "V3 Ultra"
       },
       {
         "model": "iPhone15,2",
         "os": "ios",
         "brand": "Apple",
         "name": "iPhone 14 Pro"
       }
     ],
     "meta": {
       "total_devices": 631,
       "cached_at": "2026-11-09T15:07:43.957236",
       "cache_age_days": 0.01
     }
   }

   • PASS ステータスコードが 200
   • PASS $.success が true と等しい
   • PASS $.data[0].model が存在する

   ドキュメントの GET /esims/compatible-devices リファレンス

2. 予約を一覧取得

   予約一覧は、旅行会社のeSIM注文を新しい順に返します。このリクエストはlimitで1件の予約を指定し、paginationには、条件に合う注文の件数と、次のページがあるかどうかが示されます。

   curl 'https://api.fx-port.com/api/v1/esims/bookings?limit=1' \
     -H "Authorization: Bearer fxp_test_YOUR_KEY"

   200 OK
   
   {
     "environment": "sandbox",
     "success": true,
     "data": [
       {
         "id": "639417b4-b103-4ece-bd5d-850315322278",
         "booking_id": "FX-1793546602916",
         "order_id": "20261101-106852",
         "status": "confirmed",
         "currency": "DZD",
         // ... 4 more
         "iccid": "8900000540463077957",
         // ... 9 more
       }
     ],
     "pagination": {
       "total": 61,
       "page": 1,
       "limit": 1,
       "pages": 61,
       "total_pages": 61,
       "has_more": true
     }
   }

   • PASS ステータスコードが 200
   • PASS $.data の要素数が 1件
   • PASS $.pagination.has_more が true と等しい

   ドキュメントの GET /esims/bookings リファレンス

3. 所有を確認

   所有確認は、予約が自社のものであれば、is_ownerをtrueで返します。他の旅行会社の予約と存在しない予約には同じレスポンスが返るため、この呼び出しで参照番号を探り出すことはできません。

   curl https://api.fx-port.com/api/v1/esims/bookings/FX-1793546602916/verify \
     -H "Authorization: Bearer fxp_test_YOUR_KEY"

   200 OK
   
   {
     "environment": "sandbox",
     "isOwner": true,
     "is_owner": true,
     "userAgencyId": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
     "bookingAgencyId": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d"
   }

   • PASS ステータスコードが 200
   • PASS $.is_owner が true と等しい

   ドキュメントの GET /esims/bookings/{booking_id}/verify リファレンス

4. 利用量を一括で読む

   1回の呼び出しで、iccidsに指定した複数のeSIMの利用量を読み取り、ICCIDごとに1件ずつ、それぞれのstatusとともに返します。iccidsは必ず指定してください。

   curl 'https://api.fx-port.com/api/v1/esims/usage/bulk?iccids=8900000540463077957' \
     -H "Authorization: Bearer fxp_test_YOUR_KEY"

   200 OK
   
   {
     "environment": "sandbox",
     "success": true,
     "data": [
       {
         "iccid": "8900000540463077957",
         "data": {
           "data": {
             "remaining": 1024,
             "total": 1024,
             "expired_at": "2026-11-16 15:23:29",
             "is_unlimited": false,
             "status": "ACTIVE",
             "remaining_voice": 0,
             // ... 3 more
           },
           "meta": {
             "message": "success"
           }
         },
         "status": "success"
       }
     ]
   }

   • PASS ステータスコードが 200
   • PASS $.data[0].status が success と等しい

   ドキュメントの GET /esims/usage/bulk リファレンス

すべての失敗は同じボディ形式で返り、errorsの先頭の要素に、変わることのないcodeがあります。ここでは、注文の呼び出しをあえて失敗させます。理由はそれぞれ異なり、対処も異なります。

1. 注文に読み取りキーを使用

   注文の呼び出しに読み取りキーを使うと、ボディが読み込まれる前に403とread_write_permission_requiredで拒否されます。読み取り + 書き込みキーに切り替えてください。

   curl https://api.fx-port.com/api/v1/esims/orders \
     -H "Authorization: Bearer fxp_test_YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{
     "package_id": "france-in-7days-1gb",
     "first_name": "John",
     "last_name": "Smith",
     "email": "[email protected]",
     "phone": "+15555550123",
     "description": "Order for John Smith"
   }'

   403 Forbidden
   
   {
     "environment": "sandbox",
     "success": false,
     "errors": [
       {
         "code": "read_write_permission_required",
         "type": "permission_error",
         "title": "Read write permission required",
         "message": "This endpoint requires an API key with read_write permission.",
         "field": null,
         "details": {},
         "documentation_url": "https://fx-port.com/docs/errors#read_write_permission_required"
       }
     ],
     "meta": {
       "request_id": "req_7f0c2e9a41b84d6e8a35c1d2",
       "status": 403
     },
     "request_id": "req_7f0c2e9a41b84d6e8a35c1d2"
   }

   • PASS ステータスコードが 403
   • PASS エラーコードが read_write_permission_required
   • PASS $.errors[0].type が permission_error と等しい

   ドキュメントの POST /esims/orders リファレンス

2. 無効なメールアドレス

   メールアドレスではない値は、400とinvalid_emailで拒否され、fieldにはemailが示されます。注文を再送する前に値を修正してください。同じリクエストは、同じように失敗します。

   curl https://api.fx-port.com/api/v1/esims/orders \
     -H "Authorization: Bearer fxp_test_YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{
     "package_id": "france-in-7days-1gb",
     "first_name": "John",
     "last_name": "Smith",
     "email": "traveler-at-example.com",
     "phone": "+15555550123",
     "description": "Order for John Smith"
   }'

   400 Bad Request
   
   {
     "environment": "sandbox",
     "success": false,
     "errors": [
       {
         "code": "invalid_email",
         "type": "validation_error",
         "title": "Invalid email",
         "message": "email is not a valid email address",
         "field": "email",
         "details": {},
         "documentation_url": "https://fx-port.com/docs/errors#invalid_email"
       }
     ],
     "meta": {
       "request_id": "req_7f0c2e9a41b84d6e8a35c1d2",
       "status": 400
     },
     "request_id": "req_7f0c2e9a41b84d6e8a35c1d2"
   }

   • PASS ステータスコードが 400
   • PASS エラーコードが invalid_email
   • PASS $.errors[0].field が email と等しい

   ドキュメントの POST /esims/orders リファレンス

3. 重複した注文

   すでに処理中のパッケージへの注文は、409とduplicate_requestで拒否されます。すぐに再送せず、まず予約を検索して、作成されていない場合にのみ、再度注文してください。

   curl https://api.fx-port.com/api/v1/esims/orders \
     -H "Authorization: Bearer fxp_test_YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{
     "package_id": "france-in-7days-1gb",
     "first_name": "John",
     "last_name": "Smith",
     "email": "[email protected]",
     "phone": "+15555550123",
     "description": "Order for John Smith"
   }'

   409 Conflict
   
   {
     "environment": "sandbox",
     "success": false,
     "errors": [
       {
         "code": "duplicate_request",
         "type": "conflict",
         "title": "Duplicate request",
         "message": "An identical order is already being processed. Please wait before retrying.",
         "field": null,
         "details": {},
         "documentation_url": "https://fx-port.com/docs/errors#duplicate_request"
       }
     ],
     "meta": {
       "request_id": "req_7f0c2e9a41b84d6e8a35c1d2",
       "status": 409
     },
     "request_id": "req_7f0c2e9a41b84d6e8a35c1d2"
   }

   • PASS ステータスコードが 409
   • PASS エラーコードが duplicate_request
   • PASS $.errors[0].type が conflict と等しい

   ドキュメントの POST /esims/orders リファレンス

4. リクエストが多すぎる場合

   1分あたりの制限を超えると、呼び出しは429とrate_limit_exceededで拒否され、Retry-Afterヘッダーに待つべき秒数が示されます。その後、バックオフを使ってリトライしてください。

   curl https://api.fx-port.com/api/v1/esims/orders \
     -H "Authorization: Bearer fxp_test_YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{
     "package_id": "france-in-7days-1gb",
     "first_name": "John",
     "last_name": "Smith",
     "email": "[email protected]",
     "phone": "+15555550123",
     "description": "Order for John Smith"
   }'

   429 Too Many Requests
   Retry-After: 12
   
   {
     "environment": "sandbox",
     "success": false,
     "errors": [
       {
         "code": "rate_limit_exceeded",
         "type": "rate_limit_error",
         "title": "Rate limit exceeded",
         "message": "Too many requests hit the API too quickly. Please retry your request after the time specified in the `ratelimit-reset` header.",
         "field": null,
         "details": {
           "retry_after": 12
         },
         "documentation_url": "https://fx-port.com/docs/errors#rate_limit_exceeded"
       }
     ],
     "meta": {
       "request_id": "req_7f0c2e9a41b84d6e8a35c1d2",
       "status": 429
     },
     "request_id": "req_7f0c2e9a41b84d6e8a35c1d2"
   }

   • PASS ステータスコードが 429
   • PASS エラーコードが rate_limit_exceeded
   • PASS ヘッダー Retry-After がある
   • PASS $.errors[0].details.retry_after が 12 と等しい

   ドキュメントの POST /esims/orders リファレンス