1. Startseite
  2. eSIM API

NeuREST-API mit OpenAPI-3.1-Datei

eSIM-API für Reisebüros, OTAs und Wiederverkäufer

Verkaufen Sie Reise-eSIMs über eine REST-API. Listen Sie Datenpakete nach Land auf, mit Preisen in der Währung Ihres Reisebüros, bestellen Sie eines für einen Reisenden, geben Sie ihm den QR-Code, verfolgen Sie den Verbrauch und buchen Sie nach. Eine Basis-URL bedient Sandbox und Live. Starten Sie mit einem kostenlosen Sandbox-Schlüssel; Live-Schlüssel funktionieren, sobald Ihr Reisebüro freigegeben ist.

Kostenlose Sandbox-SchlüsseleSIM-Leitfaden lesen

Die Dokumentation ist auf Englisch verfasst.

Basis-URL
https://api.fx-port.com/api/v1
Authentifizierung
Authorization: Bearer fxp_test_...
Schlüsselpräfixe
fxp_test_ / fxp_live_
Endpunkte
12
Länder mit Paketen
190+
Sprachen der Codebeispiele
9

Auf dieser Seite

  • Konsole
  • Fünf Schritte
  • Preise
  • Nach dem Verkauf
  • Endpunkte
  • Produktivbetrieb
  • Sandbox
  • Wer darauf aufbaut
  • FAQ
  • Verwandte APIs
  • Loslegen

Die eSIM-API, Aufruf für Aufruf

Verfolgen Sie einen eSIM-Verkauf Schritt für Schritt, während jede Anfrage aufgebaut, gesendet und beantwortet wird. Die Sitzungen decken den Verkauf einer eSIM ab, das Verbundenbleiben eines Reisenden, die Prüfung von Geräten und Buchungen sowie die Fehler, die Sie abfangen sollten. Anfragen und Antworten sind Beispiele aus der Dokumentation; diese Seite ruft die API nie auf.

3 Anfragen: Pakete auflisten, eSIM bestellen, Einrichtungsdaten lesen.

Beispielsitzung: Die Bodys sind Beispiele aus der Dokumentation, Datumsangaben sind nach vorn verschoben, damit sie in der Zukunft liegen, und Zeiten sind beispielhaft. Diese Seite sendet keine Anfrage.

Postman-Collection herunterladen

Paket finden, bestellen, Einrichtungsdaten lesen

Beginnen Sie mit den Paketen eines Landes, bestellen Sie eines für einen Reisenden und lesen Sie dann die Einrichtungsdaten der Bestellung. Die Sandbox erzeugt eine Test-eSIM mit einem Dummy-Aktivierungscode und bucht nichts ab; die Konsole zeigt eine gekürzte Kopie der Katalogantwort.

  1. Pakete auflisten

    Der Katalogaufruf erwartet country und type und liefert die passenden Pakete, mit Preisen in der Währung Ihres Reisebüros. Merken Sie sich die package_id des vom Reisenden gewählten Pakets.

    Anfrage GET /esims/packages
    curl 'https://api.fx-port.com/api/v1/esims/packages?country=france&type=local' \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
    Antwort 200 OK · 180 ms · 3.6 KB
    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
  }
}

    Beispiel für die Anzeige gekürzt

    • PASS Statuscode ist 200
    • PASS $.success entspricht true
    • PASS $.data[0].package_id ist vorhanden
    • PASS $.data[0].balance_debit_amount ist vorhanden

    Referenz zu GET /esims/packages in der Dokumentation

  2. eSIM bestellen

    Eine Bestellung erwartet die package_id mit E-Mail-Adresse und Telefonnummer des Reisenden. Behalten Sie booking_id und data.iccid aus der Antwort. In der Sandbox sind balanceDebited, transactionCreated und payoutCreated alle false.

    Anfrage POST /esims/orders
    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"
}'
    Antwort 200 OK · 900 ms · 1.5 KB
    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
}

    Beispiel für die Anzeige gekürzt

    • PASS Statuscode ist 200
    • PASS $.environment entspricht sandbox
    • PASS $.balance_debited entspricht false
    • PASS $.data.iccid ist vorhanden

    Referenz zu POST /esims/orders in der Dokumentation

  3. Einrichtungsdaten lesen

    Der Aufruf für die Einrichtungsdaten erwartet die booking_id und liefert den QR-Code, die Aktivierungsdaten, die Installationslinks und die Installationsschritte der Bestellung. Zeigen Sie sie nur dem Reisenden, dem die eSIM gehört.

    Anfrage GET /esims/bookings/{booking_id}/setup-instructions
    curl https://api.fx-port.com/api/v1/esims/bookings/FX-1793546602916/setup-instructions \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
    Antwort 200 OK · 210 ms · 1.8 KB
    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"
  }
}

    Beispiel für die Anzeige gekürzt

    • PASS Statuscode ist 200
    • PASS $.data.package_id entspricht france-in-7days-1gb
    • PASS $.data.sims[0].iccid ist vorhanden

    Referenz zu GET /esims/bookings/{booking_id}/setup-instructions in der Dokumentation

Verbrauch lesen, dann nachbuchen

Hat ein Reisender eine eSIM, lesen Sie, wie viel Datenvolumen übrig ist, fragen Sie, welche Pakete zu genau dieser eSIM hinzugefügt werden können, und legen Sie dann die Nachbuchung an. Der Verbrauch wird zwischengespeichert, ein Wert kann also einige Minuten alt sein. Der Nachbuchungsverlauf steht in der Seitenleiste und im Protokoll.

  1. Verbrauch lesen

    Der Verbrauchsaufruf erwartet die ICCID der Bestellung und liefert remaining und total in Megabyte, den status und das Ablaufdatum. Die Antwort stammt aus einem Cache, und force=true fragt den Anbieter erneut.

    Anfrage GET /esims/usage/{iccid}
    curl https://api.fx-port.com/api/v1/esims/usage/8900000540463077957 \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
    Antwort 200 OK · 160 ms · 261 B
    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 Statuscode ist 200
    • PASS $.data.data.status entspricht ACTIVE
    • PASS $.data.data.remaining ist vorhanden

    Referenz zu GET /esims/usage/{iccid} in der Dokumentation

  2. Nachbuchungspakete auflisten

    Dieser Aufruf listet die Pakete auf, die heute zu genau dieser eSIM hinzugefügt werden können. Eine leere Liste heißt, dass die eSIM derzeit nicht nachgebucht werden kann. Nehmen Sie die package_id der Nachbuchung aus dieser Liste, nie aus der ursprünglichen Bestellung.

    Anfrage GET /esims/topup-packages/{iccid}
    curl https://api.fx-port.com/api/v1/esims/topup-packages/8900000540463077957 \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
    Antwort 200 OK · 240 ms · 1.1 KB
    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
      }
    ]
  }
}

    Beispiel für die Anzeige gekürzt

    • PASS Statuscode ist 200
    • PASS $.data.data hat 2 Elemente
    • PASS $.data.data[0].type entspricht topup

    Referenz zu GET /esims/topup-packages/{iccid} in der Dokumentation

  3. Nachbuchung anlegen

    Eine Nachbuchung erwartet die package_id aus dieser Liste und die ICCID. Bei Live wird Ihr Guthaben erst belastet, nachdem der Anbieter zugestimmt hat. In der Sandbox ist balance in der Antwort null, und es wird nichts abgebucht.

    Anfrage POST /esims/topups
    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"
}'
    Antwort 200 OK · 900 ms · 682 B
    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 Statuscode ist 200
    • PASS $.environment entspricht sandbox
    • PASS $.balance_debited entspricht false
    • PASS $.data.balance.current entspricht 0

    Referenz zu POST /esims/topups in der Dokumentation

  4. Nachbuchungsverlauf lesen

    Der Nachbuchungsverlauf listet die Nachbuchungen einer eSIM auf, neueste zuerst. Nachbuchungen stehen nicht in der Buchungsliste; hier finden Sie sie.

    Anfrage GET /esims/bookings/{iccid}/topup-history
    curl https://api.fx-port.com/api/v1/esims/bookings/8900000540463077957/topup-history \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
    Antwort 200 OK · 130 ms · 615 B
    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 Statuscode ist 200
    • PASS $.data[0].type entspricht topup

    Referenz zu GET /esims/bookings/{iccid}/topup-history in der Dokumentation

Gerät prüfen, dann Buchungen lesen

Prüfen Sie vor dem Verkauf, ob das Telefon des Reisenden eSIM unterstützt. Lesen Sie nach dem Verkauf Ihre Buchungen und prüfen Sie, ob eine Buchungsreferenz Ihnen gehört. Der gebündelte Verbrauch steht in der Seitenleiste.

  1. Geräteliste prüfen

    Der Aufruf für kompatible Geräte liefert die Geräte, die bekanntermaßen eSIM unterstützen, mit brand, model und os. Suchen Sie das Telefon des Reisenden heraus, bevor Sie verkaufen.

    Anfrage GET /esims/compatible-devices
    curl https://api.fx-port.com/api/v1/esims/compatible-devices \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
    Antwort 200 OK · 120 ms · 283 B
    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 Statuscode ist 200
    • PASS $.success entspricht true
    • PASS $.data[0].model ist vorhanden

    Referenz zu GET /esims/compatible-devices in der Dokumentation

  2. Buchungen auflisten

    Die Buchungsliste liefert die eSIM-Bestellungen Ihres Reisebüros, neueste zuerst. Diese Anfrage ruft mit limit eine Buchung ab, und pagination gibt an, wie viele Bestellungen passen und ob eine weitere Seite folgt.

    Anfrage GET /esims/bookings
    curl 'https://api.fx-port.com/api/v1/esims/bookings?limit=1' \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
    Antwort 200 OK · 150 ms · 714 B
    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 Statuscode ist 200
    • PASS $.data hat 1 Element
    • PASS $.pagination.has_more entspricht true

    Referenz zu GET /esims/bookings in der Dokumentation

  3. Eigentum prüfen

    Die Eigentumsprüfung meldet is_owner als true, wenn die Buchung zu Ihrem Reisebüro gehört. Die Buchung eines anderen Reisebüros und eine nicht vorhandene Buchung erhalten dieselbe Antwort; der Aufruf taugt also nicht, um Referenzen zu erraten.

    Anfrage GET /esims/bookings/{booking_id}/verify
    curl https://api.fx-port.com/api/v1/esims/bookings/FX-1793546602916/verify \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
    Antwort 200 OK · 90 ms · 167 B
    200 OK

{
  "environment": "sandbox",
  "isOwner": true,
  "is_owner": true,
  "userAgencyId": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
  "bookingAgencyId": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d"
}
    • PASS Statuscode ist 200
    • PASS $.is_owner entspricht true

    Referenz zu GET /esims/bookings/{booking_id}/verify in der Dokumentation

  4. Verbrauch gebündelt lesen

    Ein Aufruf liest den Verbrauch mehrerer eSIMs aus iccids und liefert einen Eintrag pro ICCID, jeweils mit eigenem status. Senden Sie iccids immer mit.

    Anfrage GET /esims/usage/bulk
    curl 'https://api.fx-port.com/api/v1/esims/usage/bulk?iccids=8900000540463077957' \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
    Antwort 200 OK · 220 ms · 321 B
    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 Statuscode ist 200
    • PASS $.data[0].status entspricht success

    Referenz zu GET /esims/usage/bulk in der Dokumentation

Fehlschläge und wie Sie jeweils reagieren

Alle Fehlschläge teilen einen Body, und der erste Eintrag von errors hat einen stabilen code. Diese Bestellaufrufe scheitern absichtlich, jeweils aus einem anderen Grund und mit einer anderen Reaktion.

  1. Lese-Schlüssel bei Bestellung

    Ein Lese-Schlüssel beim Bestellaufruf wird mit 403 und read_write_permission_required abgewiesen, bevor der Body gelesen wird. Wechseln Sie zu einem Schlüssel mit Lesen + Schreiben.

    Anfrage POST /esims/orders
    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"
}'
    Antwort 403 Forbidden · 90 ms · 456 B
    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 Statuscode ist 403
    • PASS Fehlercode ist read_write_permission_required
    • PASS $.errors[0].type entspricht permission_error

    Referenz zu POST /esims/orders in der Dokumentation

  2. Ungültige E-Mail-Adresse

    Ein Wert, der keine E-Mail-Adresse ist, wird mit 400 und invalid_email abgewiesen, und field nennt email. Korrigieren Sie den Wert, bevor Sie die Bestellung erneut senden: Dieselbe Anfrage scheitert auf dieselbe Weise.

    Anfrage POST /esims/orders
    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"
}'
    Antwort 400 Bad Request · 100 ms · 381 B
    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 Statuscode ist 400
    • PASS Fehlercode ist invalid_email
    • PASS $.errors[0].field entspricht email

    Referenz zu POST /esims/orders in der Dokumentation

  3. Doppelte Bestellung

    Eine Bestellung für ein Paket, das bereits bearbeitet wird, wird mit 409 und duplicate_request abgewiesen. Senden Sie sie nicht sofort erneut: Suchen Sie zuerst die Buchung und bestellen Sie nur dann erneut, wenn keine angelegt wurde.

    Anfrage POST /esims/orders
    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"
}'
    Antwort 409 Conflict · 110 ms · 423 B
    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 Statuscode ist 409
    • PASS Fehlercode ist duplicate_request
    • PASS $.errors[0].type entspricht conflict

    Referenz zu POST /esims/orders in der Dokumentation

  4. Zu viele Anfragen

    Über dem Limit pro Minute wird der Aufruf mit 429 und rate_limit_exceeded abgewiesen, und der Header Retry-After nennt, wie viele Sekunden zu warten sind. Wiederholen Sie dann mit Backoff.

    Anfrage POST /esims/orders
    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"
}'
    Antwort 429 Too Many Requests · 80 ms · 504 B
    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 Statuscode ist 429
    • PASS Fehlercode ist rate_limit_exceeded
    • PASS Header Retry-After ist vorhanden
    • PASS $.errors[0].details.retry_after entspricht 12

    Referenz zu POST /esims/orders in der Dokumentation

Vom Katalog zum verbundenen Reisenden in fünf Schritten

Eine Integration ist ein kurzer Weg: Katalog lesen, Bestellung anlegen, dem Reisenden die eSIM geben, den Verbrauch verfolgen und nachbuchen, wenn das Datenvolumen aufgebraucht ist. Nur die Bestellung und die Nachbuchung verändern etwas. Jeder andere Aufruf liest nur.

Katalog für ein Reiseziel lesen

Listen Sie die Pakete eines Landes auf, mit Preisen bereits in der Währung Ihres Reisebüros, und merken Sie sich die package_id des vom Reisenden gewählten Pakets. Senden Sie immer country: Der gesamte Katalog ist eine sehr große Antwort ohne Paginierung. Lesen Sie Paket-IDs aus der Antwort, statt sie fest einzutragen, denn der Katalog ändert sich.

  • GET /api/v1/esims/packages

Anfrage

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

Antwort 200 OK

{
  "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,
      // ... 28 more
      "total_price": 468.84,
      "balance_debit_amount": 418.6,
      "b2b_price": 418.6,
      "agency_commission": "12 %",
      "commission_rate": 12,
      "currency": "DZD",
      // ... 2 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
  }
}

Paketkatalog nach Land

Bestellung anlegen

Senden Sie die package_id mit E-Mail-Adresse und Telefonnummer des Reisenden. Eine Bestellung erzeugt genau eine eSIM und belastet bei Live das Guthaben Ihres Reisebüros. Behalten Sie booking_id und ICCID aus der Antwort, denn jeder spätere Aufruf braucht eines von beiden.

  • POST /api/v1/esims/orders

Anfrage

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"
}'

Antwort 200 OK

{
  "environment": "sandbox",
  "success": true,
  "data": {
    "order": {
      "code": "20261101-106852",
      "order_id": "20261101-106852",
      "package_id": "france-in-7days-1gb",
      // ... 17 more
    },
    "sim": {
      // ... 4 more
      "qrcode": "LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741",
      // ... 7 more
      "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
}
Was die Bestellantwort enthält
FeldInhalt
booking_id Die FX-Port-Referenz der Bestellung. Bewahren Sie sie für die Einrichtungsdaten, die Eigentumsprüfung und Ihre eigenen Unterlagen auf.
data.iccid Die Kennung der eSIM. Verbrauch, Nachbuchungen und Installationsanleitungen werden alle über die ICCID abgefragt.
data.sim.qrcode data.sim.qrcode_url Die Aktivierungszeichenfolge, die der QR-Code enthält, und ein Link zum QR-Code-Bild.
data.sim.direct_apple_installation_url data.sim.sharing Ein Link, der die Installation auf einem iPhone startet, und eine Freigabeseite, auf der der Reisende die eSIM mit ihrem Zugangscode öffnen kann. Der Aufruf für die Einrichtungsdaten ergänzt den Link für Android.
Die Aktivierungsdaten sind sensibel: Zeigen Sie sie nur dem Reisenden, dem die eSIM gehört.
Hat der Anbieter die eSIM noch nicht zurückgegeben, besteht die Bestellung trotzdem: Die ICCID beginnt dann mit PENDING-, und die Daten sind über den Aufruf für die Einrichtungsdaten abrufbar, sobald der Anbieter sie hat.

eSIM-Bestellung anlegen

Dem Reisenden die eSIM übergeben

Die Antwort enthält den QR-Code und seine Aktivierungszeichenfolge, sodass Sie beides in Ihren eigenen Ansichten anzeigen können. FX-Port bittet außerdem den Anbieter, den QR-Code und einen Freigabelink per E-Mail an die Adresse des Reisenden zu senden; Sie müssen beides nicht weiterleiten. Der Aufruf für die Einrichtungsdaten liefert dieselben Daten später erneut, samt Installationsschritten.

  • GET /api/v1/esims/bookings/{booking_id}/setup-instructions

Anfrage

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

Antwort 200 OK

{
  "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",
    // ... 5 more
    "sims": [
      {
        "created_at": "2026-11-09 15:23:22",
        "iccid": "8900000540463077957",
        // ... 2 more
        "qrcode": "LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741",
        // ... 6 more
        "direct_apple_installation_url": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741",
        // ... 2 more
      }
    ],
    // ... 3 more
  }
}

Einrichtungsdaten per Buchung oder ICCID

Verbrauch verfolgen

Lesen Sie das verbleibende Datenvolumen und das Ablaufdatum einer eSIM über ihre ICCID. Die Antwort wird bis zu 15 Minuten zwischengespeichert; nutzen Sie sie daher für eine Ansicht oder eine Erinnerung, nicht als Zähler.

  • GET /api/v1/esims/usage/{iccid}

Anfrage

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

Antwort 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"
    }
  }
}

Einzel- und Sammelverbrauch von eSIMs

Nachbuchen, wenn das Datenvolumen endet

Listen Sie die Pakete auf, die zu genau dieser eSIM hinzugefügt werden können, und legen Sie die Nachbuchung mit einem davon an. Ist die Liste leer, kann die eSIM derzeit nicht nachgebucht werden, und der Reisende braucht eine neue.

  • GET /api/v1/esims/topup-packages/{iccid}
  • POST /api/v1/esims/topups

Anfrage

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"
}'

Antwort 200 OK

{
  "environment": "sandbox",
  "success": true,
  "data": {
    "topup": {
      "code": "20261101-106853",
      "order_id": "20261101-106853",
      "package_id": "france-in-7days-1gb-topup",
      "package": "KPN France Data only-1 GB - 7 days",
      "data": "1 GB",
      "validity": 7,
      "price": 468.84,
      // ... 6 more
    },
    "iccid": "8900000540463077957",
    "balance": {
      "previous": 0,
      "current": 0,
      "currency": "DZD"
    }
  },
  "booking_id": "FX-1793546625391",
  "message": "eSIM topup completed successfully",
  "balanceDebited": false,
  "balance_debited": false,
  "transactionCreated": false,
  "transaction_created": false,
  "payoutCreated": false,
  "payout_created": false
}

Nachbuchungen prüfen und anlegen

Preise, Provision und Ihr Guthaben

Jedes Paket trägt seine Betragsfelder, auf dem Server in der Währung Ihres Reisebüros berechnet. Ein Preis im Anfrage-Body wird ignoriert; eine Bestellung wird also immer zu dem Preis angelegt, den der Server berechnet.

Betragsfelder eines eSIM-Pakets
FeldInhalt
base_price price Der Paketpreis vor Ihrer Provision. Es ist nicht der Betrag, der von Ihrem Guthaben abgebucht wird.
total_price retail_price Der Preis, den Sie dem Reisenden berechnen, einschließlich Ihrer Provision.
balance_debit_amount b2b_price Der Betrag, der von Ihrem Guthaben abgebucht wird, wenn Sie das Paket bei Live bestellen. Lesen Sie den Wert, rechnen Sie ihn nicht selbst aus.
agency_commission commission_rate Ihr Provisionssatz, als Text und als Zahl. Buchungen liefern Ihre Provision stattdessen als Betrag.

Im Katalogbeispiel zahlt der Reisende 468.84 DZD. Eine Bestellung bei Live belastet Ihr Guthaben mit 418.60 DZD, und die Differenz von 50.24 DZD ist Ihre Provision.

Der Satz gehört zu Ihrem Reisebüro

Der Provisionssatz kommt mit jedem Paket zurück und ist nicht für jedes Reisebüro gleich. Ein Reisebüro mit Firmenvertrag kann einen Satz von null haben; dann entspricht der Gesamtpreis der Abbuchung.

Felder lesen, nicht nachbauen

Die Abbuchung kann höher sein als der Basispreis, weil Beträge, die für Ihr Reisebüro gelten, darin enthalten sind. Lesen Sie daher balance_debit_amount und berechnen Sie den Wert nie aus base_price. Das Wort price bedeutet im Katalog den Basispreis, in Bestellungen, Nachbuchungspaketen und Einrichtungsdaten aber den Verkaufspreis: Verwenden Sie überall base_price und total_price, dann entfällt die Mehrdeutigkeit.

Preise in der Währung Ihres Reisebüros

Jeder Betrag ist bereits in die Währung Ihres Reisebüros umgerechnet, gleich in welcher Währung der Anbieter arbeitet. Die Antwort zeigt auch die Währung des Anbieters und den Wechselkurs, sodass Sie den Kurs selbst prüfen können und nie erneut umrechnen müssen.

Wie eSIM-Preise aufgebaut sind

Nach dem Verkauf: Verbrauch, Nachbuchungen und Einrichtungsdaten

Ein Verkauf endet nicht mit der Bestellung. Diese Aufrufe halten den Reisenden verbunden und funktionieren nur bei eSIMs, die Ihr Reisebüro in der Umgebung Ihres Schlüssels bestellt hat.

Verbrauch lesen und wie aktuell er ist

Der Verbrauchsaufruf liefert das verbleibende Datenvolumen, das Kontingent, den Status und das Ablaufdatum einer eSIM oder von bis zu 50 eSIMs in einem Aufruf. FX-Port hält die letzte Antwort bis zu 15 Minuten vor, um die Ratenlimits des Anbieters zu schonen; ein Wert kann also so alt sein. Übergeben Sie force=true, um den Anbieter erneut zu fragen, zum Beispiel direkt nach einer Nachbuchung. Tun Sie das nicht bei jeder Anfrage, denn der Anbieter begrenzt, wie oft der Verbrauch gelesen werden darf. Kann der Anbieter nicht antworten, erhalten Sie den zuletzt bekannten Wert, als veraltet markiert.

Einzel- und Sammelverbrauch von eSIMs

Nachbuchungen: erst fragen, dann anlegen

Eine Nachbuchung besteht aus zwei Aufrufen. Listen Sie zuerst die Pakete auf, die zu genau dieser eSIM hinzugefügt werden können, und legen Sie dann die Nachbuchung mit einer der zurückgegebenen Paket-IDs an. Verwenden Sie nie die Paket-ID der ursprünglichen Bestellung, und heben Sie kein Nachbuchungspaket für später auf: Fragen Sie erneut, wenn der Reisende nachbuchen möchte. Eine Nachbuchung fügt der eSIM Datenvolumen hinzu und ersetzt nicht, was noch übrig ist; lesen Sie das Ergebnis daher über den Verbrauch mit force=true.

Nachbuchungen prüfen und anlegen

Wenn eine Nachbuchung nicht möglich ist

Anbieter entscheiden, welche Mobilfunknetzbetreiber ein Land versorgen, und wechseln in seltenen Fällen einen davon. Die eSIM kann dann bis zu ihrem Ablauf weiterarbeiten, während ihr Paket nicht mehr nachgebucht werden kann. Die Liste der Nachbuchungspakete kommt leer zurück. Lehnt ein Anbieter eine Nachbuchung ab, bleibt Ihr Guthaben unberührt, und der Versuch wird als fehlgeschlagene Buchung gespeichert. Die Antwort ist ein supplier_error, auf den Sie reagieren können.

Warum eine Nachbuchung nicht verfügbar sein kann

Einrichtungsdaten und Installationsschritte

Der Aufruf für die Einrichtungsdaten liefert den QR-Code, die Aktivierungsdaten, die Installationslinks und die Installationsschritte einer Bestellung, wann immer Sie sie brauchen. Der Anleitungsaufruf liefert die Schritte je Betriebssystem, in der angeforderten Sprache. Die Schritte sind allgemeiner Text des Anbieters; zeigen Sie sie daher neben dem QR-Code der Bestellung an. Zeigen Sie beides nur dem Reisenden, dem die eSIM gehört.

Einrichtungsdaten per Buchung oder ICCID

Buchungen, Nachbuchungsverlauf und Eigentum

Die Buchungsliste liefert die eSIM-Bestellungen Ihres Reisebüros in der Umgebung Ihres Schlüssels, neueste zuerst. Sie können nach Buchungs-ID, Name des Reisenden, E-Mail-Adresse, Paketname oder ICCID suchen. Nachbuchungen stehen nicht in dieser Liste: Lesen Sie sie über den Nachbuchungsverlauf einer eSIM. Bevor Sie um eine Buchungs-ID einen Link oder eine Ansicht bauen, sagt Ihnen die Eigentumsprüfung, ob sie Ihnen gehört. Die Buchung eines anderen Reisebüros und eine nicht vorhandene Buchung erhalten dieselbe Antwort.

eSIM-Buchungen auflisten und prüfen

Alle eSIM-Endpunkte, mit OpenAPI, Postman und Codebeispielen

Die eSIM-API hat 12 Endpunkte unter einer Basis-URL. Jede Zeile öffnet die Referenzseite des Aufrufs, mit Anfragefeldern, Antworten, Fehlern und Beispielen in 9 Sprachen.

Endpunkte der eSIM-API mit Methode, Pfad, Schlüsselberechtigung und Zweck
EndpunktFunktionSchlüssel
GET /api/v1/esims/packagesListet die Pakete eines Landes oder einer Region auf, mit Preisen bereits in der Währung Ihres Reisebüros. Senden Sie immer ein Land: Der gesamte Katalog ist sehr groß und hat keine Paginierung.Lesen
GET /api/v1/esims/compatible-devicesDie Geräte, die bekanntermaßen eSIM unterstützen, zur Prüfung, bevor der Reisende kauft.Lesen
POST /api/v1/esims/ordersErzeugt aus einem Paket eine eSIM für einen Reisenden und richtet sie beim Anbieter ein. Bei Live belastet es das Guthaben Ihres Reisebüros.Lesen + Schreiben
GET /api/v1/esims/topup-packages/{iccid}Die Pakete, die heute zu genau einer eSIM hinzugefügt werden können. Eine leere Liste heißt, dass sie derzeit nicht nachgebucht werden kann.Lesen
POST /api/v1/esims/topupsFügt einer bestehenden eSIM ein Nachbuchungspaket hinzu. Bei Live wird Ihr Guthaben erst belastet, nachdem der Anbieter zugestimmt hat.Lesen + Schreiben
GET /api/v1/esims/usage/{iccid}Das verbleibende Datenvolumen, das Kontingent, der Status und das Ablaufdatum einer eSIM. Die Antwort kann bis zu 15 Minuten alt sein.Lesen
GET /api/v1/esims/usage/bulkDer Verbrauch von bis zu 50 eSIMs in einem Aufruf, ein Eintrag pro ICCID, jeweils mit eigenem Status.Lesen
GET /api/v1/esims/bookingsDie eSIM-Bestellungen Ihres Reisebüros, neueste zuerst, mit Suche und Paginierung. Nachbuchungen stehen nicht in dieser Liste.Lesen
GET /api/v1/esims/bookings/{iccid}/topup-historyDie Nachbuchungen einer eSIM, neueste zuerst. Die Liste ist leer, wenn die eSIM keine hat.Lesen
GET /api/v1/esims/bookings/{booking_id}/verifyPrüft, ob eine Buchungsreferenz zu Ihrem Reisebüro gehört, bevor Sie darum einen Link oder eine Ansicht bauen.Lesen
GET /api/v1/esims/bookings/{booking_id}/setup-instructionsDer QR-Code, die Aktivierungsdaten, die Installationslinks und die Installationsschritte einer Bestellung, als JSON.Lesen
GET /api/v1/esims/instructions/{iccid}Schritt-für-Schritt-Installationsanleitung für eine ICCID, je Betriebssystem, in der angeforderten Sprache.Lesen

OpenAPI 3.1

Eine Datei beschreibt jeden Endpunkt und jedes Feld. Erzeugen Sie daraus einen Client, importieren Sie sie in ein API-Werkzeug oder geben Sie sie einem Coding-Assistenten.

OpenAPI-3.1-Datei

Postman-Collection

Die eSIM-Collection deckt alle 12 Endpunkte ab, in Ordnern entlang der Phasen eines Verkaufs. Sie enthält keine Schlüssel; tragen Sie Ihre eigenen ein.

eSIM-Postman-Collection

Codebeispiele in 9 Sprachen

Jede Referenzseite zeigt ihre Anfrage in cURL, Node.js, Python, PHP, Go, Java, C#, Swift und Kotlin, erzeugt aus der OpenAPI-Beschreibung. Jede eSIM-Anfrage gibt es in allen diesen Sprachen.

Vollständige API-Referenz

Dokumentation für KI-Assistenten

llms.txt und llms-full.txt geben KI-Assistenten die Dokumentation als reinen Text, und jede Dokuseite lässt sich als Markdown lesen, indem Sie .md an ihre Adresse anhängen.

llms.txt-Index für KI-Werkzeuge

Dokumentation der eSIM-API

Für den Produktivbetrieb gebaut: Schlüssel, Fehler, Wiederholungen und Caching

Eine eSIM-Integration wird im Produktivbetrieb an Authentifizierung, Fehlern, Wiederholungen, Caching und Ratenlimits gemessen. Das sollten Sie zu jedem Punkt wissen.

Eine Basis-URL, zwei Arten von Schlüsseln

Jede Anfrage trägt einen Schlüssel als Bearer-Token im Header Authorization. Das Präfix sagt, wo der Schlüssel funktioniert: fxp_test_ für die Sandbox und fxp_live_ für Live. Beide nutzen dieselbe Basis-URL, und jede JSON-Antwort nennt in environment die Umgebung, aus der sie stammt. Schlüssel gehören auf Ihren Server, nie in einen Browser oder eine App. FX-Port speichert von jedem Schlüssel nur einen Hash, ein verlorener Schlüssel kann daher nicht erneut angezeigt werden. Eine Änderung an einem Schlüssel kann einige Minuten brauchen, bis sie gilt.

Umgebungen und Postman-Collections

Welcher Schlüssel welchen Aufruf darf

Ein Lese-Schlüssel kann Pakete auflisten, Geräte prüfen, den Verbrauch lesen und Buchungen lesen. Für eine Bestellung oder Nachbuchung ist ein Schlüssel mit Lesen + Schreiben nötig; ein Lese-Schlüssel, der es versucht, erhält read_write_permission_required. Jeder Schlüssel lässt sich auf eine Liste von IP-Adressen beschränken, und ein Aufruf von einer anderen Adresse erhält ip_not_allowed. Verwenden Sie einen Lese-Schlüssel überall dort, wo der Code Ergebnisse nur anzeigt.

Schlüssel und Berechtigungsstufen

Ein Fehlerformat für jeden Fehlschlag

Ein fehlgeschlagener Aufruf liefert ein Array errors. Sein erster Eintrag hat einen stabilen code, einen type, der die passende Reaktion angibt, und das fehlerhafte field. Testen Sie den Code, nie die Meldung. Die gemeinsame Fehlerliste für Flüge, Hotels, eSIMs und das Konto umfasst 180 Codes. Lehnt der Anbieter eine Bestellung oder Nachbuchung ab, lautet die Antwort supplier_error mit dem eigenen HTTP-Status des Anbieters. Es wird nichts abgebucht, und eine fehlgeschlagene Buchung wird gespeichert. Direkt nach einem Neustart können der Katalog und die Geräteliste mit 202 und success gleich false antworten: Warten Sie einige Sekunden und fragen Sie erneut.

Die vollständige Liste der Fehlercodes

Wiederholen, ohne doppelt zu bestellen

FX-Port hat keinen Idempotenzschlüssel, es gibt also keinen Header Idempotency-Key zum Senden. Lesende Aufrufe dürfen gefahrlos wiederholt werden; das Anlegen einer Bestellung oder Nachbuchung nicht. FX-Port lehnt ein offensichtliches Duplikat mit 409 und duplicate_request ab: eine Bestellung für ein Paket, das noch bearbeitet wird. Bei Live lehnt es außerdem dasselbe Paket ab, das innerhalb von 60 Sekunden nach der letzten bestätigten Bestellung Ihres Reisebüros erneut bestellt wird, gleich für welchen Reisenden. Bestellungen antworten meist in wenigen Sekunden, ein langsamer Anbieter kann aber deutlich länger brauchen. Läuft ein Aufruf in eine Zeitüberschreitung oder bricht die Verbindung ab, senden Sie die Bestellung nicht sofort erneut, denn die eSIM kann bereits existieren. Suchen Sie sie mit dem Parameter search der Buchungsliste über die E-Mail-Adresse des Reisenden und bestellen Sie nur dann erneut, wenn nichts angelegt wurde.

Sicher wiederholen nach Zeitüberschreitung

Keine Webhooks: bei Bedarf abfragen

FX-Port ruft keine URL von Ihnen auf, weder in der Sandbox noch bei Live. Eine Bestellung antwortet mit der eSIM oder mit einem Platzhalter PENDING-, solange der Anbieter sie noch nicht zurückgegeben hat. Alles Weitere fragen Sie bei Bedarf ab: die Einrichtungsdaten, den Verbrauch oder die Buchungsliste.

Caching und Geschwindigkeit

Der Verbrauch wird bis zu 15 Minuten vorgehalten und die Liste der Nachbuchungspakete einige Minuten; force=true umgeht den Cache. Der ungefilterte Katalog ist eine sehr große Antwort ohne Paginierung, senden Sie daher country und akzeptieren Sie Kompression mit Accept-Encoding: gzip. Paketnamen kommen in der Sprache des Parameters locale zurück; die erste Anfrage in einer anderen Sprache als Englisch ist langsamer, weil der Text dann geholt und danach zwischengespeichert wird.

Ratenlimits

Limits werden pro Schlüssel und pro Minute in zwei Gruppen gezählt, und jede Antwort enthält ratelimit-limit und ratelimit-remaining, sodass Sie langsamer werden können, bevor Anfragen abgewiesen werden. Warten Sie nach einem 429 die Sekunden aus Retry-After ab und wiederholen Sie die Anfrage mit exponentiellem Backoff und Jitter. Laufen zu viele Bestellungen oder Aufladungen eines Schlüssels oder einer Agentur gleichzeitig, kann die Antwort concurrency_limit_exceeded lauten.

Ratenlimits der eSIM-API pro Schlüssel
Art des AufrufsPro Minute
Bestellungen und Nachbuchungen anlegen1,200
Jeder andere eSIM-Endpunkt6,000

Die Obergrenze für gleichzeitig laufende Bestellungen und Aufladungen befindet sich derzeit im Beobachtungsmodus: Sie wird gezählt, aber nicht durchgesetzt, sodass deswegen noch nichts abgewiesen wird; der Changelog kündigt den Tag an, ab dem sie durchgesetzt wird. Verstehen Sie diese Zahlen als aktuelle Regelung, nicht als Zusage. Sandbox-Schlüssel haben dieselben Zähler pro Minute wie Live-Schlüssel; planen Sie Lasttests daher ein, statt sie in einer Schleife laufen zu lassen.

Ratenlimits pro Schlüssel

Namen und Versionen

Anfragefelder sind snake_case, etwa first_name und agent_id. Ältere Schreibweisen funktionieren weiterhin: user_id wird als agent_id gelesen und erzeugt einen Eintrag in warnings, während customer_email ohne einen solchen Eintrag als email akzeptiert wird. Viele Antworten behalten einen älteren Schlüssel neben seinem snake_case-Pendant mit demselben Wert, etwa order_id neben code, und ?naming=snake liefert ausschließlich snake_case-Schlüssel. Die Version steht im Pfad, /api/v1: Eine inkompatible Änderung würde ein neues Präfix erhalten, neue Felder und Schreibweisen sind dagegen additiv.

In der kostenlosen Sandbox starten, dann live gehen

Alles auf dieser Seite funktioniert heute in der Sandbox. Ein Sandbox-Schlüssel ist kostenlos und selbst anzulegen, und er berührt nie Ihr echtes Guthaben.

  1. 1

    Konto erstellen

    Registrieren Sie sich für ein FX-Port-Konto. Sandbox-Schlüssel sind kostenlos, und Sandbox-Buchungen verursachen keine echten Kosten.

    FX-Port-Konto erstellen

  2. 2

    Sandbox-Schlüssel erstellen

    Erstellen Sie auf der API-Seite Ihres Dashboards einen Schlüssel, der mit fxp_test_ beginnt. Ein Lese-Schlüssel kann suchen und lesen; ein Schlüssel mit Lesen + Schreiben kann zusätzlich Testbuchungen anlegen.

    API-Seite des Dashboards öffnen

  3. 3

    Erste Anfrage senden

    Es gibt eine einzige Basis-URL, und der Schlüssel steht als Bearer-Token im Header Authorization. Die Schnellstartanleitung führt Sie durch den ersten Aufruf.

    API-Schnellstart lesen

  4. 4

    Live gehen, wenn Sie bereit sind

    Tauschen Sie den Schlüssel gegen einen fxp_live_-Schlüssel aus. Live funktioniert, sobald Ihr Reisebüro freigegeben ist; bis dahin antwortet die API mit 403 agency_not_active. Echte Buchungen werden aus einem aufgeladenen Guthaben bezahlt.

    Den Wechsel zu Live nachlesen

Eine erste Katalog-Anfrage in cURL. Die Dokumentation zeigt dieselbe Anfrage in jeder unterstützten Sprache.

Anfrage

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

Schnellstart: erster Sandbox-Aufruf

Was die Sandbox leistet

Eine Bestellung in der Sandbox erzeugt beim Anbieter eine echte Test-eSIM mit einem Dummy-Aktivierungscode; sie lässt sich daher nicht auf einem Telefon installieren. Es wird nichts abgebucht, und die Antworten sagen das: balanceDebited, transactionCreated und payoutCreated sind alle false. Eine Nachbuchung antwortet mit einem Guthaben von null. Der Verbrauch ist statisch: Eine neue eSIM zeigt ihr volles Kontingent und den Status ACTIVE. Sandbox-Buchungen sind nur für Sandbox-Schlüssel sichtbar.

eSIMs in der Sandbox

Was nur Live testen kann

Die Guthabenprüfung, die Duplikatprüfung und die Guthabensperre laufen nur bei Live. Die Antworten 402 mit insufficient_balance, 409 für dasselbe Paket, das innerhalb von 60 Sekunden erneut bestellt wird, und 503 mit balance_lock_timeout erscheinen daher nie in der Sandbox. Schreiben Sie deren Behandlung anhand der Liste der Fehlercodes.

Die vollständige Liste der Fehlercodes

Live gehen

Live-Schlüssel sind an die Freigabe des Reisebüros gebunden: Solange Ihr Reisebüro nicht freigegeben ist, antwortet ein Live-Schlüssel mit agency_not_active, und Ihr Sandbox-Schlüssel funktioniert weiter. Live-Bestellungen werden aus einem aufgeladenen Guthaben des Reisebüros bezahlt. Der Wechsel zu Live ändert den Schlüssel, nicht den Code, denn Sandbox und Live teilen sich eine Basis-URL.

Freigabe für Live-Schlüssel erforderlich

Wer auf der eSIM-API aufbaut

Jede Zielgruppe stützt sich auf einen anderen Teil derselben Aufrufe.

Reisebüros, die Reisen verkaufen

Reisebüros verkaufen eine eSIM neben dem Flug und dem Hotel. Sie bestellen mit der eigenen E-Mail-Adresse des Reisenden, damit der Anbieter den QR-Code und einen Freigabelink sendet, und lesen den Verbrauch, wenn ein Reisender fragt. Der Provisionssatz kommt mit jedem Paket zurück, und agent_id hält fest, welcher Nutzer Ihres Reisebüros eine Bestellung aufgegeben hat.

OTAs und Marktplätze

Marktplätze bauen zuerst die Stöberseite: ein Land nach dem anderen, lokale oder regionale Pakete, die Netze und das Datenvolumen jedes Pakets und eine Geräteprüfung, bevor der Reisende kauft. Eine Ansicht, die die eSIMs eines Reisenden auflistet, kann den Verbrauch von bis zu 50 davon in einem Aufruf lesen.

Reisetechnologie- und Firmenteams

Reisetechnologie-Teams und Reiseabteilungen von Unternehmen bauen eigene Buchungswerkzeuge. Alles, was sie für den Start brauchen, ist öffentlich: die OpenAPI-Datei, die Postman-Collection und Dokumentation als reiner Text, die ein KI-Coding-Assistent lesen kann, sodass der erste Prototyp vom echten Vertrag ausgeht.

eSIM-API: häufige Fragen

Was ist die FX-Port eSIM-API, und für wen ist sie gedacht?

Es ist eine REST-API, mit der ein Reisebüro, eine OTA oder ein Wiederverkäufer Reise-eSIMs mit Datenvolumen über eine Integration verkaufen kann. Sie listen die Pakete eines Reiseziels mit Preisen in der Währung Ihres Reisebüros auf und bestellen eines für einen Reisenden. Sie geben dem Reisenden den QR-Code, verfolgen den Verbrauch und buchen nach. Alles ist JSON über HTTPS, und eine OpenAPI-Datei beschreibt jeden Endpunkt.

Gibt es eine kostenlose Sandbox, und wie bekomme ich einen Schlüssel?

Ja. Legen Sie ein FX-Port-Konto an, öffnen Sie die API-Seite Ihres Dashboards und erstellen Sie einen Sandbox-Schlüssel; das geht selbstständig und kostenlos. Eine Bestellung in der Sandbox erzeugt eine Test-eSIM mit einem Dummy-Aktivierungscode; sie lässt sich daher nicht auf einem Telefon installieren. Von Ihrem Guthaben wird nichts abgebucht. Sandbox und Live teilen sich eine Basis-URL, der getestete Code ist also der Code, den Sie ausliefern.

Was ist nötig, um live zu gehen?

Ihr Reisebüro muss freigegeben sein, bevor ein Live-Schlüssel funktioniert. Bis dahin wird ein Live-Schlüssel abgewiesen, und Ihr Sandbox-Schlüssel funktioniert weiter. Live-Bestellungen werden aus einem aufgeladenen Guthaben des Reisebüros bezahlt, das die Sandbox nie berührt, und jeder Schlüssel lässt sich auf eine Liste von IP-Adressen beschränken. Der Wechsel ändert nur den Schlüssel; jede Antwort nennt die Umgebung, aus der sie stammt.

Welche Länder und Pakete kann ich verkaufen?

Pakete gibt es für mindestens 190 Länder, und regionale Bündel erscheinen unter ihrer Region. Die Pakete unterscheiden sich in Datenvolumen, Gültigkeit, Netzen und darin, ob sie nachgebucht werden können. Lesen Sie diese Felder und die Paket-ID aus der Katalogantwort, statt sie fest einzutragen. Fragen Sie jeweils ein Land ab, denn der gesamte Katalog ist eine sehr große Antwort. Eine separate Geräteliste erlaubt es, das Telefon des Reisenden vor dem Verkauf zu prüfen.

Wie erhält der Reisende die eSIM?

Die Bestellantwort enthält den QR-Code, seine Aktivierungszeichenfolge, einen Installationslink für das iPhone und eine Freigabeseite. Sie können sie in Ihren eigenen Ansichten anzeigen. FX-Port bittet außerdem den Anbieter, den QR-Code und einen Freigabelink per E-Mail an die Adresse des Reisenden zu senden, sobald die eSIM erzeugt ist. Hat der Anbieter die eSIM noch nicht zurückgegeben, besteht die Bestellung trotzdem, und die Daten sind später über den Aufruf für die Einrichtungsdaten abrufbar.

Wie hängen Preise, Provision und mein Guthaben zusammen?

Jedes Paket trägt diese Betragsfelder in der Währung Ihres Reisebüros: den Basispreis vor Ihrer Provision, den Gesamtpreis für den Reisenden, den von Ihrem Guthaben abgebuchten Betrag und Ihren Provisionssatz. Ihre Provision ist der Gesamtpreis minus die Abbuchung. Lesen Sie diese Felder, statt sie nachzubauen, denn die Abbuchung gilt speziell für Ihr Reisebüro. In der Sandbox wird nichts abgebucht; bei Live wird die Abbuchung vom Guthaben Ihres Reisebüros vorgenommen.

Kann ich eine eSIM nachbuchen, und wie sehe ich, was übrig ist?

Ja, in zwei Aufrufen: Listen Sie die Pakete auf, die zu genau dieser eSIM hinzugefügt werden können, und legen Sie dann die Nachbuchung mit einem davon an. Eine Nachbuchung ist nicht immer möglich, denn ein Anbieter kann den Netzbetreiber eines Landes wechseln. Eine leere Liste heißt dann, dass der Reisende eine neue eSIM braucht. Der Verbrauch wird bis zu 15 Minuten zwischengespeichert, behandeln Sie ihn also als einen kürzlich ermittelten Wert; ein Aufruf liest bis zu 50 eSIMs.

Wie werden Fehler gemeldet, und gibt es Webhooks?

Ein Fehler kommt in einem einheitlichen Format mit einem stabilen Fehlercode zurück, und diesen Code sollte Ihr Programm prüfen, nicht den Meldungstext. Lesende Aufrufe lassen sich mit Backoff gefahrlos wiederholen. Das Anlegen einer Bestellung oder Nachbuchung ist anders: Es gibt keinen Idempotenzschlüssel, suchen Sie also nach einer Zeitüberschreitung zuerst die Buchung, bevor Sie es erneut versuchen. FX-Port lehnt ein offensichtliches Duplikat ab, etwa dasselbe Paket, das bei Live innerhalb von 60 Sekunden zweimal bestellt wird. Webhooks gibt es nicht.

Kann ich eine eSIM-Bestellung über die API stornieren oder erstatten?

Nein. Die API hat keinen Endpunkt, um eine eSIM-Bestellung zu stornieren oder zu erstatten. Jede Bestellung erzeugt genau eine eSIM, prüfen Sie daher Paket und Angaben des Reisenden, bevor Sie sie senden. Lehnt der Anbieter eine Bestellung ab, wird nichts abgebucht, und eine fehlgeschlagene Buchung wird gespeichert. Bei einem Problem mit einer bestimmten Bestellung schreiben Sie dem Entwicklerteam und nennen Sie deren Buchungs-ID.

Was brauche ich zum Start, und welche Werkzeuge helfen?

Sie brauchen einen Sandbox-Schlüssel und einen HTTP-Client. Die Dokumentation ergänzt eine OpenAPI-3.1-Datei, eine Postman-Collection, Codebeispiele in 9 Sprachen und Exporte als reiner Text für KI-Assistenten. Bewahren Sie Ihre Schlüssel auf Ihrem Server auf, nie in einem Browser oder einer App. Länger dauern dagegen Ihr eigener Checkout, die Zustellung des QR-Codes an den Reisenden und die Fehlerbehandlung.

Weitere FX-Port-APIs

Eine eSIM gehört meist zu einer Reise. Flüge und Hotels nutzen dieselben Schlüssel, dasselbe Fehlerformat und dieselben Konventionen wie eSIMs, und ihre Buchungen stehen im selben Kontoverlauf.

  • Flug-API

    Flüge suchen, bepreisen und buchen, gehaltene Bestellungen bezahlen, stornieren und Tickets abrufen.

  • Hotel-API

    Hotels finden, Raten prüfen, vorbuchen und buchen, Voucher abrufen und stornieren.

  • Transfer-APIVorschau

    Angebote für Flughafentransfers einholen, buchen, verfolgen und stornieren.

Lieber keinen Code schreiben? Reisebüros können eSIMs auch über das FX-Port-Dashboard verkaufen. eSIMs über das Dashboard verkaufen

Starten Sie Ihre erste eSIM-Bestellung in der Sandbox

Legen Sie ein Konto an, erstellen Sie einen Sandbox-Schlüssel, listen Sie Pakete auf, legen Sie eine Bestellung an und lesen Sie noch heute den Verbrauch. Live-Schlüssel folgen, sobald Ihr Reisebüro freigegeben ist.

Konto erstellenEntwicklerteam anschreiben

Einen KI-Assistenten zu dieser API fragen

Öffnen Sie diese Seite in einem Assistenten und bitten Sie um einen schrittweisen Integrationsplan.

FX-PORT

Ihre vertrauenswürdige B2B-Reisevertriebsplattform. Greifen Sie auf globales Inventar zu und wachsen Sie mit Ihrem Unternehmen mit besseren Preisen und einfachen Tools.

  • Bedingungen
  • Datenschutz
  • Kontaktiere uns
  • Unternehmen
  • Blog
  • B2B Flug API
  • B2B Transfer API
  • B2B Fähren API
  • B2B Hotel API
  • B2B eSIM API
  • B2B-Bettenbank
  • B2B Flug Konsolidator
  • Fluggesellschaften
  • Flughäfen
  • Länder
  • eSIMs

Flugdienste

FX-Port ist eine umfassende B2B-Flugvertriebsplattform, die es Reiseagenturen ermöglicht, weltweit Flugtickets zuzugreifen und zu verkaufen. Mit Verbindungen zu über 500 Fluggesellschaften können Agenturen wettbewerbsfähige Großhandelspreise mit sofortigen Bestätigungen und automatisiertem Ticketing anbieten.

Unsere Plattform bietet Echtzeit-Verfügbarkeit, Preisvergleichstools und automatisiertes Buchungsmanagement. Reiseagenturen können auf exklusive B2B-Flugtarife zugreifen, Provisionen verwalten und ihre Flugoperationen über unser integriertes System rationalisieren.

Unterkunftsdienste

Greifen Sie auf unser umfangreiches Netzwerk von über 1,5 Millionen Immobilien weltweit über unsere B2B-Hotelbuchungsplattform zu. Reiseagenturen können wettbewerbsfähige Preise mit garantierten Margen und sofortigen Zimmerbestätigungen in allen Unterkunftskategorien anbieten.

Von Luxusresorts bis hin zu budgetfreundlichen Optionen bietet unsere Plattform umfassende Immobilieninformationen, dynamische Preisgestaltung und automatisiertes Buchungsmanagement für nahtlose Hotelverteilung.

Reiselösungen

Umfassende Transferservices mit einem globalen Netzwerk verifizierter Anbieter, die Flughafentransfers, Stadtrundfahrten und professionelle Chauffeurdienste anbieten. Unser Fährbuchungssystem verbindet große maritime Routen mit sofortigen Buchungsmöglichkeiten und wettbewerbsfähigen B2B-Preisen.

Spezialisierte Umrah-Pakete mit End-to-End-Services, einschließlich Visabearbeitung, Unterkunft und Transport. Maßgeschneiderte Reisepakete mit dynamischer Preisgestaltung und automatisiertem Inventarmanagement für Reiseagenturen.

FX-Port revolutioniert den B2B-Reisevertrieb mit modernster Technologie und umfassenden Lösungen. Unsere Plattform ermöglicht es Reiseagenturen, auf globales Inventar zuzugreifen, Buchungen effizient zu verwalten und ihr Geschäft mit wettbewerbsfähigen Preisen und automatisierten Tools zu wachsen.

Mit Unterstützung für mehrere Währungen, lokale Zahlungsabwicklung und 24/7-Kundendienst stellen wir sichere Operationen für Reiseagenturen weltweit sicher. Unsere Plattform bietet Echtzeit-Verfügbarkeit, sofortige Bestätigungen und umfassende Buchungsverwaltungstools.

Reiseagenturen können unsere Plattform nutzen, um eine vollständige Palette von Reisediensten anzubieten, darunter Flugbuchungen, Hotelreservierungen, Transferservices, Fährtickets, Umrah-Pakete und maßgeschneiderte Reiseerlebnisse. Unser B2B-Marktplatz verbindet Agenturen mit verifizierten Anbietern weltweit.

FX-Port bietet Sicherheit auf Unternehmensebene, automatisiertes Provisionsmanagement und detaillierte Analysen für das Geschäftswachstum. Treten Sie Hunderten erfolgreicher Agenturen bei, die unsere Plattform nutzen, um ihre Operationen zu rationalisieren und ihre Marktpräsenz zu erweitern.

© 2026 FX-PORT. Alle Rechte vorbehalten.

Zum Inhalt springen
FX-Port für AnbieterFlüge—Fluggesellschaften·Konsolidierer·OTAs·GDS-AgenturenHotels—Bettenbanken·PMS/CMS·HotelsAlle Reiseanbieter
UnternehmenAPI
Anmelden
Jetzt Zugang erhalten
Dashboard