1. Accueil
  2. eSIM API

NouveauAPI REST avec un fichier OpenAPI 3.1

API eSIM pour agences de voyages, OTA et revendeurs

Vendez des eSIM de voyage via une seule API REST. Listez les forfaits data par pays avec des prix dans la devise de votre agence, commandez-en un pour un voyageur, remettez-lui le QR code, suivez la consommation et rechargez. Une seule URL de base sert la Sandbox et le Live. Commencez avec une clé Sandbox gratuite ; les clés Live fonctionnent une fois votre agence approuvée.

Obtenir des clés Sandbox gratuitesLire le guide eSIM

La documentation est rédigée en anglais.

URL de base
https://api.fx-port.com/api/v1
Authentification
Authorization: Bearer fxp_test_...
Préfixes de clés
fxp_test_ / fxp_live_
Endpoints
12
Pays avec forfaits
190+
Langages d’exemples de code
9

Sur cette page

  • Console
  • Cinq étapes
  • Prix
  • Après la vente
  • Endpoints
  • Production
  • Sandbox
  • Qui construit dessus
  • FAQ
  • API associées
  • Démarrer

L’API eSIM, appel par appel

Suivez la vente d’une eSIM pas à pas, au fil de la construction, de l’envoi et de la réponse de chaque requête. Les sessions couvrent la vente d’une eSIM, le maintien de la connexion du voyageur, la vérification des appareils et des réservations, et les échecs qu’il vaut la peine de gérer. Les requêtes et les réponses sont des exemples tirés de la documentation, et cette page n’appelle jamais l’API.

3 requêtes : Lister les forfaits, Commander l’eSIM, Lire les données d’installation.

Session illustrative : les corps de requête et de réponse sont des exemples tirés de la documentation, les dates sont décalées pour rester postérieures à aujourd’hui et les durées sont indicatives. Cette page n’envoie aucune requête.

Télécharger la collection Postman

Trouver un forfait, le commander, lire les données d’installation

Commencez par les forfaits d’un pays, commandez-en un pour un voyageur, puis lisez les données d’installation de la commande. La Sandbox crée une eSIM de test avec un code d’activation factice et ne débite rien ; la console montre une copie abrégée de la réponse du catalogue.

  1. Lister les forfaits

    L’appel du catalogue prend country et type et renvoie les forfaits correspondants, avec des prix dans la devise de votre agence. Conservez le package_id de celui que choisit le voyageur.

    Requête GET /esims/packages
    curl 'https://api.fx-port.com/api/v1/esims/packages?country=france&type=local' \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
    Réponse 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
  }
}

    Exemple abrégé pour l’affichage

    • PASS Le code de statut est 200
    • PASS $.success est égal à true
    • PASS $.data[0].package_id existe
    • PASS $.data[0].balance_debit_amount existe

    Référence de GET /esims/packages dans la documentation

  2. Commander l’eSIM

    Créer une commande demande le package_id avec l’adresse e-mail et le numéro de téléphone du voyageur. Conservez booking_id et data.iccid de la réponse. En Sandbox, balanceDebited, transactionCreated et payoutCreated valent tous false.

    Requête 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"
}'
    Réponse 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
}

    Exemple abrégé pour l’affichage

    • PASS Le code de statut est 200
    • PASS $.environment est égal à sandbox
    • PASS $.balance_debited est égal à false
    • PASS $.data.iccid existe

    Référence de POST /esims/orders dans la documentation

  3. Lire les données d’installation

    L’appel des données d’installation prend le booking_id et renvoie le QR code, les données d’activation, les liens d’installation et les étapes d’installation de la commande. Ne les montrez qu’au voyageur qui possède l’eSIM.

    Requête 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"
    Réponse 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"
  }
}

    Exemple abrégé pour l’affichage

    • PASS Le code de statut est 200
    • PASS $.data.package_id est égal à france-in-7days-1gb
    • PASS $.data.sims[0].iccid existe

    Référence de GET /esims/bookings/{booking_id}/setup-instructions dans la documentation

Lire la consommation, puis recharger

Une fois que le voyageur a une eSIM, lisez la quantité de données restantes, demandez quels forfaits peuvent être ajoutés à cette eSIM précise, puis créez la recharge. La consommation est mise en cache : un chiffre peut dater de quelques minutes. L’historique des recharges se trouve dans la barre latérale et dans la transcription.

  1. Lire la consommation

    L’appel de consommation prend l’ICCID de la commande et renvoie remaining et total en mégaoctets, le status et l’expiration. La réponse vient d’un cache, et force=true interroge de nouveau le fournisseur.

    Requête GET /esims/usage/{iccid}
    curl https://api.fx-port.com/api/v1/esims/usage/8900000540463077957 \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
    Réponse 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 Le code de statut est 200
    • PASS $.data.data.status est égal à ACTIVE
    • PASS $.data.data.remaining existe

    Référence de GET /esims/usage/{iccid} dans la documentation

  2. Lister les forfaits de recharge

    Cet appel liste les forfaits qui peuvent être ajoutés aujourd’hui à cette eSIM précise. Une liste vide signifie que l’eSIM ne peut pas être rechargée pour le moment. Prenez le package_id de la recharge dans cette liste, jamais dans la commande d’origine.

    Requête GET /esims/topup-packages/{iccid}
    curl https://api.fx-port.com/api/v1/esims/topup-packages/8900000540463077957 \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
    Réponse 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
      }
    ]
  }
}

    Exemple abrégé pour l’affichage

    • PASS Le code de statut est 200
    • PASS $.data.data contient 2 éléments
    • PASS $.data.data[0].type est égal à topup

    Référence de GET /esims/topup-packages/{iccid} dans la documentation

  3. Créer la recharge

    Créer une recharge demande le package_id de cette liste et l’ICCID. En Live, votre solde n’est débité qu’une fois la recharge acceptée par le fournisseur. En Sandbox, le balance de la réponse est à zéro et rien n’est débité.

    Requête 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"
}'
    Réponse 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 Le code de statut est 200
    • PASS $.environment est égal à sandbox
    • PASS $.balance_debited est égal à false
    • PASS $.data.balance.current est égal à 0

    Référence de POST /esims/topups dans la documentation

  4. Lire l’historique des recharges

    L’historique des recharges liste les recharges d’une eSIM, de la plus récente à la plus ancienne. Les recharges ne figurent pas dans la liste des réservations : c’est donc ici que vous les trouvez.

    Requête 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"
    Réponse 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 Le code de statut est 200
    • PASS $.data[0].type est égal à topup

    Référence de GET /esims/bookings/{iccid}/topup-history dans la documentation

Vérifier un appareil, puis lire vos réservations

Avant la vente, vérifiez que le téléphone du voyageur prend en charge l’eSIM. Après la vente, lisez vos réservations et vérifiez qu’une référence de réservation est bien la vôtre. La consommation en lot figure dans la barre latérale.

  1. Consulter la liste des appareils

    L’appel des appareils compatibles renvoie les appareils connus pour prendre en charge l’eSIM, avec brand, model et os. Cherchez le téléphone du voyageur avant de vendre.

    Requête GET /esims/compatible-devices
    curl https://api.fx-port.com/api/v1/esims/compatible-devices \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
    Réponse 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 Le code de statut est 200
    • PASS $.success est égal à true
    • PASS $.data[0].model existe

    Référence de GET /esims/compatible-devices dans la documentation

  2. Lister vos réservations

    La liste des réservations renvoie les commandes eSIM de votre agence, de la plus récente à la plus ancienne. Cette requête demande une réservation avec limit, et pagination indique combien de commandes correspondent et si une autre page suit.

    Requête GET /esims/bookings
    curl 'https://api.fx-port.com/api/v1/esims/bookings?limit=1' \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
    Réponse 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 Le code de statut est 200
    • PASS $.data contient 1 élément
    • PASS $.pagination.has_more est égal à true

    Référence de GET /esims/bookings dans la documentation

  3. Vérifier l’appartenance

    La vérification d’appartenance répond is_owner à true quand la réservation appartient à votre agence. Une réservation d’une autre agence et une réservation inexistante reçoivent la même réponse : l’appel ne permet donc pas de découvrir des références.

    Requête 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"
    Réponse 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 Le code de statut est 200
    • PASS $.is_owner est égal à true

    Référence de GET /esims/bookings/{booking_id}/verify dans la documentation

  4. Lire la consommation en lot

    Un appel lit la consommation de plusieurs eSIM listées dans iccids et renvoie une entrée par ICCID, chacune avec son propre status. Envoyez toujours iccids.

    Requête GET /esims/usage/bulk
    curl 'https://api.fx-port.com/api/v1/esims/usage/bulk?iccids=8900000540463077957' \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
    Réponse 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 Le code de statut est 200
    • PASS $.data[0].status est égal à success

    Référence de GET /esims/usage/bulk dans la documentation

Les échecs et comment réagir à chacun

Tous les échecs partagent un même corps, et la première entrée de errors a un code stable. Ces appels de commande échouent volontairement, chacun pour une raison différente et avec une réaction différente.

  1. Clé Lecture sur une commande

    Une clé Lecture sur l’appel de commande est refusée avec 403 et read_write_permission_required, avant la lecture du corps. Passez à une clé Lecture + écriture.

    Requête 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"
}'
    Réponse 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 Le code de statut est 403
    • PASS Le code d’erreur est read_write_permission_required
    • PASS $.errors[0].type est égal à permission_error

    Référence de POST /esims/orders dans la documentation

  2. Adresse e-mail invalide

    Une valeur qui n’est pas une adresse e-mail est refusée avec 400 et invalid_email, et field désigne email. Corrigez la valeur avant de renvoyer la commande : la même requête échoue de la même façon.

    Requête 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"
}'
    Réponse 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 Le code de statut est 400
    • PASS Le code d’erreur est invalid_email
    • PASS $.errors[0].field est égal à email

    Référence de POST /esims/orders dans la documentation

  3. Commande en double

    Une commande pour un forfait déjà en cours de traitement est refusée avec 409 et duplicate_request. Ne la renvoyez pas tout de suite : cherchez d’abord la réservation, et ne passez une nouvelle commande que si aucune n’a été créée.

    Requête 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"
}'
    Réponse 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 Le code de statut est 409
    • PASS Le code d’erreur est duplicate_request
    • PASS $.errors[0].type est égal à conflict

    Référence de POST /esims/orders dans la documentation

  4. Trop de requêtes

    Au-delà de la limite par minute, l’appel est refusé avec 429 et rate_limit_exceeded, et l’en-tête Retry-After indique combien de secondes attendre. Réessayez ensuite avec un backoff.

    Requête 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"
}'
    Réponse 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 Le code de statut est 429
    • PASS Le code d’erreur est rate_limit_exceeded
    • PASS L’en-tête Retry-After est présent
    • PASS $.errors[0].details.retry_after est égal à 12

    Référence de POST /esims/orders dans la documentation

Du catalogue au voyageur connecté en cinq étapes

Une intégration tient en un court parcours : lire le catalogue, créer la commande, remettre l’eSIM au voyageur, suivre la consommation et recharger quand les données sont épuisées. Seules la commande et la recharge modifient quelque chose. Tous les autres appels se contentent de lire.

Lire le catalogue d’une destination

Listez les forfaits d’un pays, avec des prix déjà dans la devise de votre agence, et conservez le package_id de celui que choisit le voyageur. Envoyez toujours country : le catalogue entier est une très grosse réponse sans pagination. Lisez les identifiants de forfaits dans la réponse au lieu de les coder en dur, car le catalogue évolue.

  • GET /api/v1/esims/packages

Requête

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

Réponse 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
  }
}

Catalogue de forfaits par pays

Créer la commande

Envoyez le package_id avec l’adresse e-mail et le numéro de téléphone du voyageur. Une commande crée exactement une eSIM et, en Live, débite le solde de votre agence. Conservez le booking_id et l’ICCID de la réponse, car chaque appel suivant en demande un.

  • POST /api/v1/esims/orders

Requête

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

Réponse 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
}
Ce que contient la réponse de la commande
ChampCe qu’il contient
booking_id La référence FX-Port de la commande. Conservez-la pour les données d’installation, la vérification d’appartenance et vos propres dossiers.
data.iccid L’identifiant de l’eSIM. La consommation, les recharges et les instructions d’installation sont toutes demandées à partir de l’ICCID.
data.sim.qrcode data.sim.qrcode_url La chaîne d’activation encodée par le QR code, et un lien vers l’image du QR code.
data.sim.direct_apple_installation_url data.sim.sharing Un lien qui lance l’installation sur un iPhone, et une page de partage où le voyageur peut ouvrir l’eSIM avec son code d’accès. L’appel des données d’installation ajoute le lien pour Android.
Les données d’activation sont sensibles : ne les montrez qu’au voyageur qui possède l’eSIM.
Si le fournisseur n’a pas encore renvoyé l’eSIM, la commande existe quand même : l’ICCID commence par PENDING-, et les données sont disponibles via l’appel des données d’installation dès que le fournisseur les a.

Créer une commande eSIM

Remettre l’eSIM au voyageur

La réponse contient le QR code et sa chaîne d’activation, que vous pouvez afficher dans vos propres écrans. FX-Port demande aussi au fournisseur d’envoyer par e-mail le QR code et un lien de partage à l’adresse du voyageur, sans que vous ayez à le relayer. L’appel des données d’installation renvoie plus tard les mêmes données, avec les étapes d’installation.

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

Requête

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

Réponse 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
  }
}

Données d’installation par réservation ou ICCID

Suivre la consommation

Lisez les données restantes et l’expiration d’une eSIM à partir de son ICCID. La réponse est mise en cache jusqu’à 15 minutes : servez-vous-en pour un écran ou un rappel, pas comme compteur.

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

Requête

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

Réponse 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"
    }
  }
}

Consommation eSIM, unitaire et en lot

Recharger quand les données sont épuisées

Listez les forfaits qui peuvent être ajoutés à cette eSIM précise, puis créez la recharge avec l’un d’eux. Si la liste est vide, l’eSIM ne peut pas être rechargée pour le moment et le voyageur a besoin d’une nouvelle eSIM.

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

Requête

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

Réponse 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
}

Vérifier et créer des recharges

Prix, commission et solde

Chaque forfait porte ses champs monétaires, calculés côté serveur dans la devise de votre agence. Un prix placé dans le corps d’une requête est ignoré : une commande est donc toujours créée au prix calculé par le serveur.

Champs monétaires d’un forfait eSIM
ChampCe qu’il contient
base_price price Le prix du forfait avant votre commission. Ce n’est pas le montant débité de votre solde.
total_price retail_price Le prix à facturer au voyageur, commission comprise.
balance_debit_amount b2b_price Ce qui sort du solde de votre agence quand vous commandez le forfait en Live. Lisez-le, ne le calculez pas.
agency_commission commission_rate Votre taux de commission, en texte et en nombre. Les réservations renvoient plutôt votre commission sous forme de montant.

Dans l’exemple du catalogue, le voyageur paie 468.84 DZD. Une commande en Live débite votre solde de 418.60 DZD, et la différence, 50.24 DZD, est votre commission.

Le taux est propre à votre agence

Le taux de commission revient avec chaque forfait, et il n’est pas le même pour toutes les agences. Une agence d’entreprise sous contrat peut avoir un taux nul ; le prix total est alors égal au débit.

Lisez les champs, ne les reconstruisez pas

Le débit peut être supérieur au prix de base, car des montants propres à votre agence en font partie. Lisez donc balance_debit_amount et ne le calculez jamais à partir de base_price. Le mot price désigne le prix de base dans le catalogue, mais le prix de vente dans les commandes, les forfaits de recharge et les données d’installation : utilisez base_price et total_price partout et l’ambiguïté disparaît.

Tarifé dans la devise de votre agence

Chaque montant est déjà converti dans la devise de votre agence, quelle que soit la devise du fournisseur. La réponse indique aussi la devise du fournisseur et le taux de change : vous pouvez vérifier le taux vous-même et n’avez jamais besoin de reconvertir.

Comment les prix eSIM sont construits

Après la vente : consommation, recharges et données d’installation

Une vente ne s’arrête pas à la commande. Ces appels maintiennent le voyageur connecté, et ils ne fonctionnent que sur les eSIM que votre agence a commandées dans le même environnement que votre clé.

Lire la consommation et sa fraîcheur

La consommation renvoie les données restantes, la dotation, le statut et l’expiration d’une eSIM, ou de 50 eSIM au maximum en un seul appel. FX-Port conserve la dernière réponse jusqu’à 15 minutes pour protéger les limites de débit du fournisseur : un chiffre peut donc avoir cet âge. Passez force=true pour interroger de nouveau le fournisseur, par exemple juste après une recharge. Ne le faites pas à chaque requête, car le fournisseur limite la fréquence de lecture de la consommation. Si le fournisseur ne peut pas répondre, vous recevez le dernier chiffre connu, signalé comme périmé.

Consommation eSIM, unitaire et en lot

Recharges : demander d’abord, créer ensuite

Une recharge se fait en deux appels. Listez d’abord les forfaits qui peuvent être ajoutés à cette eSIM précise, puis créez la recharge avec l’un des identifiants de forfait renvoyés. Ne réutilisez jamais l’identifiant du forfait de la commande d’origine, et ne gardez pas un forfait de recharge pour plus tard : redemandez quand le voyageur veut recharger. Une recharge ajoute des données à l’eSIM et ne remplace pas ce qui reste ; lisez donc le résultat dans la consommation avec force=true.

Vérifier et créer des recharges

Quand une recharge n’est pas possible

Les fournisseurs choisissent quels opérateurs mobiles desservent un pays et, dans de rares cas, ils en changent. L’eSIM peut alors continuer à fonctionner jusqu’à son expiration, alors que son forfait ne peut plus être rechargé. La liste des forfaits de recharge revient vide. Si un fournisseur rejette une recharge, votre solde n’est pas touché et la tentative est enregistrée comme réservation échouée. La réponse est un supplier_error auquel vous pouvez réagir.

Pourquoi une recharge peut être indisponible

Données d’installation et étapes d’installation

L’appel des données d’installation renvoie, à la demande, le QR code, les données d’activation, les liens d’installation et les étapes d’installation d’une commande. L’appel des instructions renvoie les étapes par système d’exploitation, dans la langue demandée. Ces étapes sont un texte générique du fournisseur : affichez-les à côté du QR code de la commande. Ne montrez les deux qu’au voyageur qui possède l’eSIM.

Données d’installation par réservation ou ICCID

Réservations, historique des recharges et appartenance

La liste des réservations renvoie les commandes eSIM de votre agence dans l’environnement de votre clé, de la plus récente à la plus ancienne. Vous pouvez y chercher par identifiant de réservation, nom du voyageur, adresse e-mail, nom du forfait ou ICCID. Les recharges ne figurent pas dans cette liste : lisez-les avec l’historique des recharges d’une eSIM. Avant de construire un lien ou un écran autour d’un identifiant de réservation, la vérification d’appartenance indique s’il est bien le vôtre. Une réservation d’une autre agence et une réservation inexistante reçoivent la même réponse.

Lister et vérifier les réservations eSIM

Tous les endpoints eSIM, avec OpenAPI, Postman et exemples de code

L’API eSIM compte 12 endpoints sous une même URL de base. Chaque ligne ouvre la page de référence de cet appel, avec ses champs de requête, ses réponses, ses erreurs et ses exemples en 9 langages.

Endpoints de l’API eSIM avec méthode, chemin, permission de la clé et usage
EndpointFonctionClé
GET /api/v1/esims/packagesListe les forfaits d’un pays ou d’une région, avec des prix déjà dans la devise de votre agence. Envoyez toujours un pays : le catalogue entier est très volumineux et n’a pas de pagination.Lecture
GET /api/v1/esims/compatible-devicesLes appareils connus pour prendre en charge l’eSIM, pour une vérification avant l’achat du voyageur.Lecture
POST /api/v1/esims/ordersCrée une eSIM à partir d’un forfait pour un voyageur et la provisionne chez le fournisseur. En Live, elle débite le solde de votre agence.Lecture + écriture
GET /api/v1/esims/topup-packages/{iccid}Les forfaits qui peuvent être ajoutés aujourd’hui à une eSIM précise. Une liste vide signifie qu’elle ne peut pas être rechargée pour le moment.Lecture
POST /api/v1/esims/topupsAjoute un forfait de recharge à une eSIM existante. En Live, votre solde n’est débité qu’une fois la recharge acceptée par le fournisseur.Lecture + écriture
GET /api/v1/esims/usage/{iccid}Les données restantes, la dotation, le statut et l’expiration d’une eSIM. La réponse peut dater de 15 minutes au plus.Lecture
GET /api/v1/esims/usage/bulkLa consommation de 50 eSIM au maximum en un seul appel, une entrée par ICCID, chacune avec son propre statut.Lecture
GET /api/v1/esims/bookingsLes commandes eSIM de votre agence, de la plus récente à la plus ancienne, avec recherche et pagination. Les recharges ne figurent pas dans cette liste.Lecture
GET /api/v1/esims/bookings/{iccid}/topup-historyLes recharges d’une eSIM, de la plus récente à la plus ancienne. La liste est vide si l’eSIM n’en a aucune.Lecture
GET /api/v1/esims/bookings/{booking_id}/verifyVérifie qu’une référence de réservation appartient à votre agence, avant de construire un lien ou un écran autour d’elle.Lecture
GET /api/v1/esims/bookings/{booking_id}/setup-instructionsLe QR code, les données d’activation, les liens d’installation et les étapes d’installation d’une commande, en JSON.Lecture
GET /api/v1/esims/instructions/{iccid}Les instructions d’installation pas à pas pour un ICCID, par système d’exploitation, dans la langue demandée.Lecture

OpenAPI 3.1

Un fichier décrit chaque endpoint et chaque champ. Générez-en un client, importez-le dans un outil d’API ou donnez-le à un assistant de code.

Fichier OpenAPI 3.1

Collection Postman

La collection eSIM couvre les 12 endpoints dans des dossiers qui suivent les étapes d’une vente. Elle ne contient aucune clé : ajoutez les vôtres.

Collection Postman eSIM

Exemples de code en 9 langages

Chaque page de référence affiche sa requête en cURL, Node.js, Python, PHP, Go, Java, C#, Swift et Kotlin, générée à partir de la description OpenAPI. Chaque requête eSIM est disponible dans tous ces langages.

Référence complète de l’API

Documentation pour les assistants IA

llms.txt et llms-full.txt fournissent la documentation en texte brut aux assistants IA, et chaque page de la documentation peut être lue en Markdown en ajoutant .md à son adresse.

Index llms.txt pour les outils IA

Documentation de l’API eSIM

Prête pour la production : clés, erreurs, nouvelles tentatives et cache

Une intégration eSIM se juge en production sur l’authentification, les échecs, les nouvelles tentatives, le cache et les limites de débit. Voici ce qu’il faut savoir sur chacun.

Une URL de base, deux types de clés

Chaque requête porte une clé comme jeton bearer dans l’en-tête Authorization. Le préfixe indique où la clé fonctionne : fxp_test_ pour la Sandbox et fxp_live_ pour le Live. Les deux utilisent la même URL de base, et chaque réponse JSON indique l’environnement dont elle provient dans environment. Les clés doivent rester sur votre serveur, jamais dans un navigateur ou une application. FX-Port ne conserve qu’un hachage de chaque clé : une clé perdue ne peut donc pas être affichée à nouveau. Une modification de clé peut mettre quelques minutes à s’appliquer.

Environnements et collections Postman

Quelle clé pour quel appel

Une clé Lecture peut lister les forfaits, vérifier les appareils, lire la consommation et lire les réservations. Créer une commande ou une recharge exige une clé Lecture + écriture ; une clé Lecture qui l’essaie reçoit read_write_permission_required. Toute clé peut être verrouillée sur une liste d’adresses IP, et un appel depuis une autre adresse reçoit ip_not_allowed. Utilisez une clé Lecture partout où le code se contente d’afficher des résultats.

Clés et niveaux de permission

Un seul format d’erreur pour tous les échecs

Un appel en échec renvoie un tableau errors. Sa première entrée contient un code stable, un type qui indique comment réagir et le field en cause. Testez le code, jamais le message. La liste d’erreurs commune aux vols, aux hôtels, aux eSIM et au compte comprend 180 codes. Quand le fournisseur refuse une commande ou une recharge, la réponse est un supplier_error qui porte le statut HTTP propre au fournisseur. Rien n’est débité et une réservation échouée est enregistrée. Juste après un redémarrage, le catalogue et la liste des appareils peuvent répondre 202 avec success à false : attendez quelques secondes et redemandez.

La liste complète des codes d’erreur

Réessayer sans commander deux fois

FX-Port n’a pas de clé d’idempotence : il n’existe donc pas d’en-tête Idempotency-Key à envoyer. Les lectures peuvent être répétées sans risque ; créer une commande ou une recharge, non. FX-Port refuse un doublon évident avec 409 et duplicate_request : une commande pour un forfait encore en cours de traitement. En Live, il refuse aussi le même forfait commandé de nouveau dans les 60 secondes qui suivent la dernière commande confirmée de votre agence, quel que soit le voyageur. Les commandes répondent généralement en quelques secondes, mais un fournisseur lent peut mettre beaucoup plus longtemps. Si un appel expire ou si la connexion tombe, ne renvoyez pas la commande tout de suite, car l’eSIM peut exister. Cherchez-la avec le paramètre search de la liste des réservations, à partir de l’adresse e-mail du voyageur, et ne passez une nouvelle commande que si rien n’a été créé.

Réessayer sans risque après un délai dépassé

Pas de webhooks : interrogez quand vous en avez besoin

FX-Port n’appelle aucune URL de votre côté, ni en Sandbox ni en Live. Une commande répond avec l’eSIM, ou avec un espace réservé PENDING- tant que le fournisseur ne l’a pas renvoyée. Pour tout le reste, vous interrogez au moment voulu : les données d’installation, la consommation ou la liste des réservations.

Cache et rapidité

La consommation est conservée jusqu’à 15 minutes et la liste des forfaits de recharge quelques minutes ; force=true contourne le cache. Le catalogue sans filtre est une très grosse réponse sans pagination : envoyez donc country et acceptez la compression avec Accept-Encoding: gzip. Les titres des forfaits reviennent dans la langue du paramètre locale ; la première requête dans une langue autre que l’anglais est plus lente, car le texte est alors récupéré puis mis en cache.

Limites de débit

Les limites sont comptées par clé et par minute, en deux groupes, et chaque réponse porte ratelimit-limit et ratelimit-remaining : vous pouvez donc ralentir avant d’être refusé. Après un 429, attendez le nombre de secondes indiqué dans Retry-After et réessayez avec un backoff exponentiel et du jitter. Trop de commandes ou de recharges d’une même clé ou d’une même agence en simultané peuvent entraîner la réponse concurrency_limit_exceeded.

Limites de débit eSIM par clé
Type d’appelPar minute
Création de commandes et de recharges1,200
Tous les autres endpoints eSIM6,000

Pour l’instant, le plafond de commandes et de recharges simultanées est en mode observation : il est compté mais pas appliqué, donc rien n’est encore refusé à cause de lui, et le changelog annoncera le jour de son application. Lisez ces chiffres comme la politique actuelle, et non comme une promesse. Les clés Sandbox ont les mêmes compteurs par minute que les clés Live : planifiez vos tests de charge au lieu de les lancer en boucle.

Limites de débit par clé

Noms et versions

Les champs de requête sont en snake_case, comme first_name et agent_id. Les anciennes graphies fonctionnent encore : user_id est lu comme agent_id et ajoute une entrée warnings, tandis que customer_email est accepté comme email sans en ajouter. De nombreuses réponses gardent une ancienne clé à côté de son jumeau en snake_case avec la même valeur, comme order_id à côté de code, et ?naming=snake ne renvoie que des clés en snake_case. La version se trouve dans le chemin, /api/v1 : un changement incompatible recevrait un nouveau préfixe, tandis que les nouveaux champs et les nouvelles graphies s’ajoutent sans rien casser.

Commencez dans la Sandbox gratuite, puis passez en Live

Tout ce que montre cette page fonctionne dès aujourd’hui dans la Sandbox. Une clé Sandbox s’obtient en libre-service, gratuitement, et ne touche jamais votre solde réel.

  1. 1

    Créez un compte

    Inscrivez-vous sur FX-Port. Les clés sandbox sont gratuites et les réservations sandbox n’entraînent aucun frais réel.

    Créer votre compte FX-Port

  2. 2

    Créez une clé sandbox

    Sur la page API de votre tableau de bord, créez une clé commençant par fxp_test_. Une clé Lecture peut rechercher et lire ; une clé Lecture + écriture peut aussi créer des réservations de test.

    Ouvrir la page API du tableau de bord

  3. 3

    Envoyez votre première requête

    Il n’y a qu’une seule URL de base, et la clé se place dans l’en-tête Authorization sous forme de jeton Bearer. Le guide de démarrage rapide détaille un premier appel.

    Lire le guide de démarrage rapide de l’API

  4. 4

    Passez en Live quand vous êtes prêt

    Remplacez la clé par une clé fxp_live_. Le mode Live fonctionne une fois votre agence approuvée ; d’ici là, l’API répond 403 agency_not_active. Les réservations réelles sont réglées depuis un solde approvisionné.

    Lire comment fonctionne le passage en Live

Une première requête de catalogue en cURL. La documentation affiche la même requête dans chaque langage pris en charge.

Requête

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

Démarrage rapide : premier appel Sandbox

Ce que fait la Sandbox

Une commande en Sandbox crée une vraie eSIM de test chez le fournisseur, avec un code d’activation factice : elle ne peut donc pas être installée sur un téléphone. Rien n’est débité, et les réponses le disent : balanceDebited, transactionCreated et payoutCreated valent tous false. Une recharge répond avec un solde de zéro. La consommation est statique : une nouvelle eSIM affiche toute sa dotation et le statut ACTIVE. Les réservations Sandbox ne sont visibles que par les clés Sandbox.

Les eSIM dans la Sandbox

Ce que seul le Live peut tester

La vérification du solde, la détection des doublons et le verrou de solde ne s’exécutent qu’en Live. Les réponses 402 avec insufficient_balance, 409 pour le même forfait commandé de nouveau dans les 60 secondes, et 503 avec balance_lock_timeout n’apparaissent donc jamais en Sandbox. Écrivez leur gestion d’après la liste des codes d’erreur.

La liste complète des codes d’erreur

Passer en Live

Les clés Live sont liées à l’approbation de l’agence : tant que votre agence n’est pas approuvée, une clé Live répond agency_not_active et votre clé Sandbox continue de fonctionner. Les commandes Live sont payées depuis un solde d’agence approvisionné. Passer en Live change la clé, pas le code, car la Sandbox et le Live partagent une même URL de base.

Approbation requise pour les clés Live

Qui construit sur l’API eSIM

Chaque public s’appuie sur une partie différente des mêmes appels.

Les agences qui vendent des voyages

Les agences vendent une eSIM à côté du vol et de l’hôtel. Elles commandent avec l’adresse e-mail du voyageur lui-même, afin que le fournisseur envoie le QR code et un lien de partage, et elles lisent la consommation quand un voyageur le demande. Le taux de commission revient avec chaque forfait, et agent_id enregistre quel utilisateur de votre agence a passé une commande.

OTA et places de marché

Les places de marché construisent d’abord la page de navigation : un pays à la fois, des forfaits locaux ou régionaux, les réseaux et la dotation de données de chaque forfait, et une vérification de l’appareil avant l’achat du voyageur. Un écran qui liste les eSIM d’un voyageur peut lire la consommation de 50 d’entre elles au maximum en un seul appel.

Équipes de technologie du voyage et d’entreprise

Les équipes de technologie du voyage et les services voyages d’entreprise construisent leurs propres outils de réservation. Tout ce qu’il faut pour démarrer est public : le fichier OpenAPI, la collection Postman et une documentation en texte brut qu’un assistant de code IA peut lire, de sorte que le premier prototype part du vrai contrat.

API eSIM : questions fréquentes

Qu’est-ce que l’API eSIM de FX-Port, et à qui s’adresse-t-elle ?

C’est une API REST qui permet à une agence de voyages, une OTA ou un revendeur de vendre des eSIM data de voyage depuis une seule intégration. Vous listez les forfaits d’une destination avec des prix dans la devise de votre agence et en commandez un pour un voyageur. Vous lui remettez le QR code, suivez la consommation et rechargez. Tout est en JSON sur HTTPS, et un fichier OpenAPI décrit chaque endpoint.

Existe-t-il une Sandbox gratuite, et comment obtenir une clé ?

Oui. Créez un compte FX-Port, ouvrez la page API de votre tableau de bord et créez une clé Sandbox ; vous pouvez le faire vous-même, sans frais. Une commande en Sandbox crée une eSIM de test avec un code d’activation factice : elle ne peut donc pas être installée sur un téléphone. Rien n’est débité de votre solde. La Sandbox et le Live partagent une même URL de base : le code que vous testez est celui que vous livrez.

Que faut-il pour passer en Live ?

Votre agence doit être approuvée pour qu’une clé Live fonctionne. D’ici là, une clé Live est refusée et votre clé Sandbox continue de fonctionner. Les commandes Live sont payées depuis un solde d’agence approvisionné, que la Sandbox ne touche jamais, et toute clé peut être verrouillée sur une liste d’adresses IP. Pour basculer, il suffit de changer la clé ; chaque réponse indique l’environnement dont elle provient.

Quels pays et quels forfaits puis-je vendre ?

Des forfaits sont disponibles pour plus de 190 pays, et les forfaits régionaux apparaissent sous leur région. Les forfaits diffèrent par la dotation de données, la validité, les réseaux et la possibilité de les recharger. Lisez ces champs et l’identifiant du forfait dans la réponse du catalogue au lieu de les coder en dur. Demandez un pays à la fois, car le catalogue entier est une très grosse réponse. Une liste d’appareils distincte permet de vérifier le téléphone d’un voyageur avant la vente.

Comment le voyageur reçoit-il l’eSIM ?

La réponse de la commande contient le QR code, sa chaîne d’activation, un lien d’installation pour iPhone et une page de partage. Vous pouvez les afficher dans vos propres écrans. FX-Port demande aussi au fournisseur d’envoyer par e-mail le QR code et un lien de partage à l’adresse du voyageur dès que l’eSIM est créée. Si le fournisseur n’a pas encore renvoyé l’eSIM, la commande existe quand même et les données sont disponibles plus tard via l’appel des données d’installation.

Comment s’articulent les prix, la commission et mon solde ?

Chaque forfait porte ces champs monétaires dans la devise de votre agence : le prix de base avant votre commission, le prix total à facturer au voyageur, le montant débité de votre solde et votre taux de commission. Votre commission est le prix total moins le débit. Lisez ces champs au lieu de les reconstruire, car le débit est propre à votre agence. En Sandbox, rien n’est débité ; en Live, le débit sort du solde de votre agence.

Puis-je recharger une eSIM, et comment voir ce qu’il reste ?

Oui, en deux appels : listez les forfaits qui peuvent être ajoutés à l’eSIM précise, puis créez la recharge avec l’un d’eux. Une recharge n’est pas toujours possible, car un fournisseur peut changer l’opérateur d’un pays. Une liste vide signifie alors que le voyageur a besoin d’une nouvelle eSIM. La consommation est mise en cache jusqu’à 15 minutes : considérez-la comme un chiffre récent. Un seul appel lit jusqu’à 50 eSIM.

Comment les échecs sont-ils signalés, et y a-t-il des webhooks ?

Un échec revient dans un format unique, avec un code d’erreur stable ; c’est ce code que votre programme doit tester, pas le texte du message. Les lectures peuvent être répétées sans risque avec un backoff. Créer une commande ou une recharge est différent : il n’y a pas de clé d’idempotence, donc après un délai dépassé, cherchez la réservation avant de réessayer. FX-Port refuse un doublon évident, comme le même forfait commandé deux fois en moins de 60 secondes en Live. Il n’y a pas de webhooks.

Puis-je annuler ou rembourser une commande eSIM via l’API ?

Non. L’API n’a aucun endpoint pour annuler ou rembourser une commande eSIM. Chaque commande crée exactement une eSIM : vérifiez donc le forfait et les informations du voyageur avant de l’envoyer. Si le fournisseur refuse une commande, rien n’est débité et une réservation échouée est enregistrée. Pour un problème sur une commande précise, écrivez à l’équipe développeurs en indiquant son identifiant de réservation.

De quoi ai-je besoin pour démarrer, et quels outils aident ?

Il vous faut une clé Sandbox et un client HTTP. La documentation ajoute un fichier OpenAPI 3.1, une collection Postman, des exemples de code dans 9 langages et des exports en texte brut pour les assistants IA. Gardez vos clés sur votre serveur, jamais dans un navigateur ou une application. Ce qui prend plus de temps, c’est votre propre parcours d’achat, la remise du QR code au voyageur et la gestion des erreurs.

Les autres API FX-Port

Une eSIM accompagne généralement un voyage. Les vols et les hôtels utilisent les mêmes clés, le même corps d’erreur et les mêmes conventions que les eSIM, et leurs réservations figurent dans le même historique de compte.

  • API Vols

    Recherchez, tarifez et réservez des vols, réglez les commandes mises en attente, annulez et consultez les billets.

  • API Hôtels

    Trouvez des hôtels, vérifiez les tarifs, préréservez et réservez, consultez les vouchers et annulez.

  • API TransfertsPréversion

    Obtenez un devis, réservez, suivez et annulez des transferts aéroport.

Vous préférez ne pas écrire de code ? Les agences peuvent aussi vendre des eSIM depuis le tableau de bord FX-Port. Vendre des eSIM depuis le tableau de bord

Passez votre première commande eSIM dans la Sandbox

Créez un compte, générez une clé Sandbox, listez les forfaits, créez une commande et lisez la consommation dès aujourd’hui. Les clés Live suivent une fois votre agence approuvée.

Créer votre compteÉcrire à l’équipe développeurs

Interrogez un assistant IA sur cette API

Ouvrez cette page dans un assistant et demandez un plan d’intégration pas à pas.

FX-PORT

Votre plateforme de distribution B2B de confiance. Accédez à l'inventaire mondial et développez votre entreprise avec de meilleurs tarifs et des outils faciles.

  • Conditions
  • Confidentialité
  • Contactez-nous
  • Entreprise
  • Blog
  • API Vols B2B
  • API Transferts B2B
  • API Ferries B2B
  • API Hôtels B2B
  • B2B eSIM API
  • Bed Bank B2B
  • Consolidateur de Vols B2B
  • Compagnies Aériennes
  • Aéroports
  • Pays
  • eSIM

Services Aériens

FX-Port est une plateforme complète de distribution de vols B2B permettant aux agences de voyages d'accéder et de vendre des billets d'avion dans le monde entier. Avec des connexions à plus de 500 compagnies aériennes, les agences peuvent offrir des tarifs de gros compétitifs avec des confirmations instantanées et une billetterie automatisée.

Notre plateforme fournit une disponibilité en temps réel, des outils de comparaison de prix et une gestion automatisée des réservations. Les agences de voyages peuvent accéder à des tarifs aériens B2B exclusifs, gérer les commissions et rationaliser leurs opérations aériennes grâce à notre système intégré.

Services d'Hébergement

Accédez à notre vaste réseau de plus de 1,5 million de propriétés dans le monde via notre plateforme de réservation d'hôtels B2B. Les agences de voyages peuvent offrir des tarifs compétitifs avec des marges garanties et des confirmations de chambres instantanées dans toutes les catégories d'hébergement.

Des complexes de luxe aux options économiques, notre plateforme fournit des informations complètes sur les propriétés, une tarification dynamique et une gestion automatisée des réservations pour une distribution hôtelière fluide.

Solutions de Voyage

Services de transfert complets avec un réseau mondial de fournisseurs vérifiés, offrant des transferts aéroportuaires, des visites de ville et des services de chauffeur professionnel. Notre système de réservation de ferry relie les principales routes maritimes avec des capacités de réservation instantanée et des tarifs B2B compétitifs.

Forfaits Omra spécialisés avec des services complets incluant le traitement des visas, l'hébergement et le transport. Forfaits de voyage personnalisés avec tarification dynamique et gestion automatisée des stocks pour les agences de voyages.

FX-Port révolutionne la distribution de voyages B2B avec une technologie de pointe et des solutions complètes. Notre plateforme permet aux agences de voyages d'accéder à l'inventaire mondial, de gérer efficacement les réservations et de développer leur activité avec des tarifs compétitifs et des outils automatisés.

Avec la prise en charge de plusieurs devises, le traitement des paiements locaux et un service client 24/7, nous assurons des opérations fluides pour les agences de voyages du monde entier. Notre plateforme propose une disponibilité en temps réel, des confirmations instantanées et des outils complets de gestion des réservations.

Les agences de voyages peuvent utiliser notre plateforme pour offrir une gamme complète de services de voyage, y compris les réservations de vols, les réservations d'hôtels, les services de transfert, les billets de ferry, les forfaits Omra et les expériences de voyage personnalisées. Notre marketplace B2B connecte les agences avec des fournisseurs vérifiés dans le monde entier.

FX-Port fournit une sécurité de niveau entreprise, une gestion automatisée des commissions et des analyses détaillées pour la croissance des entreprises. Rejoignez des centaines d'agences prospères qui utilisent notre plateforme pour rationaliser leurs opérations et étendre leur présence sur le marché.

© 2026 FX-PORT. Tous droits réservés.

Passer au contenu
FX-Port pour les fournisseursVols—Compagnies aériennes·Consolidateurs·OTA·Agences GDSHôtels—Bed banks·PMS/CMS·HôtelsTous les fournisseurs de voyage
EntrepriseAPI
Connexion
Obtenir l'accès
Tableau de bord