1. Inicio
  2. eSIM API

NuevoAPI REST con archivo OpenAPI 3.1

API de eSIM para agencias de viajes, OTA y revendedores

Vende eSIM de viaje con una sola API REST. Lista paquetes de datos por país con precios en la moneda de tu agencia, pide uno para un viajero, entrégale el código QR, consulta el consumo y recarga. Una única URL base sirve para sandbox y Live. Empieza con una clave sandbox gratis; las claves Live funcionan cuando tu agencia está aprobada.

Obtener claves sandbox gratisLeer la guía de eSIM

La documentación está escrita en inglés.

URL base
https://api.fx-port.com/api/v1
Autenticación
Authorization: Bearer fxp_test_...
Prefijos de clave
fxp_test_ / fxp_live_
Endpoints
12
Países con paquetes
190+
Lenguajes de ejemplo
9

En esta página

  • Consola
  • Cinco pasos
  • Precios
  • Posventa
  • Endpoints
  • Producción
  • Sandbox
  • Quién la usa
  • FAQ
  • APIs relacionadas
  • Empezar

La API de eSIM, llamada a llamada

Sigue la venta de una eSIM paso a paso, mientras cada solicitud se construye, se envía y recibe respuesta. Las sesiones cubren la venta de una eSIM, cómo mantener conectado al viajero, la comprobación de dispositivos y reservas, y los fallos que conviene gestionar. Las solicitudes y respuestas son ejemplos de la documentación, y esta página nunca llama a la API.

3 solicitudes: Listar los paquetes, Pedir la eSIM, Leer datos de instalación.

Sesión ilustrativa: los cuerpos son ejemplos de la documentación, las fechas se adelantan para que siempre sean posteriores a hoy y los tiempos son ilustrativos. Esta página no envía ninguna solicitud.

Descargar la colección de Postman

Encuentra un paquete, pídelo y lee los datos de instalación

Empieza con los paquetes de un país, pide uno para un viajero y lee después los datos de instalación del pedido. El sandbox crea una eSIM de prueba con un código de activación ficticio y no descuenta nada, y la consola muestra una copia reducida de la respuesta del catálogo.

  1. Listar los paquetes

    La llamada del catálogo recibe country y type y devuelve los paquetes que coinciden, con precios en la moneda de tu agencia. Guarda el package_id del que elija el viajero.

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

    Ejemplo recortado para mostrarlo

    • PASS El código de estado es 200
    • PASS $.success es igual a true
    • PASS $.data[0].package_id existe
    • PASS $.data[0].balance_debit_amount existe

    Referencia de GET /esims/packages en la documentación

  2. Pedir la eSIM

    Crear un pedido requiere el package_id con el correo electrónico y el teléfono del viajero. Guarda booking_id y data.iccid de la respuesta. En el sandbox, balanceDebited, transactionCreated y payoutCreated son todos false.

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

    Ejemplo recortado para mostrarlo

    • PASS El código de estado es 200
    • PASS $.environment es igual a sandbox
    • PASS $.balance_debited es igual a false
    • PASS $.data.iccid existe

    Referencia de POST /esims/orders en la documentación

  3. Leer datos de instalación

    La llamada de datos de instalación recibe el booking_id y devuelve el código QR, los datos de activación, los enlaces de instalación y los pasos de instalación del pedido. Muéstralos solo al viajero titular de la eSIM.

    Solicitud 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"
    Respuesta 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"
  }
}

    Ejemplo recortado para mostrarlo

    • PASS El código de estado es 200
    • PASS $.data.package_id es igual a france-in-7days-1gb
    • PASS $.data.sims[0].iccid existe

    Referencia de GET /esims/bookings/{booking_id}/setup-instructions en la documentación

Lee el consumo y recarga

Cuando un viajero ya tiene una eSIM, lee cuántos datos le quedan, pregunta qué paquetes se pueden añadir a esa eSIM concreta y crea la recarga. El consumo se guarda en caché, así que una cifra puede tener minutos de antigüedad. El historial de recargas está en la barra lateral y en la transcripción.

  1. Leer el consumo

    La llamada de consumo recibe el ICCID del pedido y devuelve remaining y total en megabytes, el status y la caducidad. La respuesta sale de una caché, y force=true vuelve a preguntar al proveedor.

    Solicitud GET /esims/usage/{iccid}
    curl https://api.fx-port.com/api/v1/esims/usage/8900000540463077957 \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
    Respuesta 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 El código de estado es 200
    • PASS $.data.data.status es igual a ACTIVE
    • PASS $.data.data.remaining existe

    Referencia de GET /esims/usage/{iccid} en la documentación

  2. Listar paquetes de recarga

    Esta llamada lista los paquetes que hoy se pueden añadir a esa eSIM concreta. Una lista vacía significa que la eSIM no se puede recargar ahora. Toma el package_id de la recarga de esta lista, nunca del pedido original.

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

    Ejemplo recortado para mostrarlo

    • PASS El código de estado es 200
    • PASS $.data.data tiene 2 elementos
    • PASS $.data.data[0].type es igual a topup

    Referencia de GET /esims/topup-packages/{iccid} en la documentación

  3. Crear la recarga

    Crear una recarga requiere el package_id de esa lista y el ICCID. En Live, tu saldo se descuenta solo después de que el proveedor la acepte. En el sandbox el balance de la respuesta es cero y no se descuenta nada.

    Solicitud 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"
}'
    Respuesta 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 El código de estado es 200
    • PASS $.environment es igual a sandbox
    • PASS $.balance_debited es igual a false
    • PASS $.data.balance.current es igual a 0

    Referencia de POST /esims/topups en la documentación

  4. Leer historial de recargas

    El historial de recargas lista las recargas de una eSIM, de la más reciente a la más antigua. Las recargas no están en la lista de reservas, así que aquí es donde las encuentras.

    Solicitud 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"
    Respuesta 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 El código de estado es 200
    • PASS $.data[0].type es igual a topup

    Referencia de GET /esims/bookings/{iccid}/topup-history en la documentación

Comprueba un dispositivo y lee tus reservas

Antes de la venta, comprueba que el teléfono del viajero admite eSIM. Después de la venta, lee tus reservas y comprueba que una referencia de reserva es tuya. El consumo masivo aparece en la barra lateral.

  1. Consultar dispositivos

    La llamada de dispositivos compatibles devuelve los dispositivos que admiten eSIM, con brand, model y os. Busca el teléfono del viajero antes de vender.

    Solicitud GET /esims/compatible-devices
    curl https://api.fx-port.com/api/v1/esims/compatible-devices \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
    Respuesta 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 El código de estado es 200
    • PASS $.success es igual a true
    • PASS $.data[0].model existe

    Referencia de GET /esims/compatible-devices en la documentación

  2. Listar tus reservas

    La lista de reservas devuelve los pedidos de eSIM de tu agencia, del más reciente al más antiguo. Esta solicitud pide una reserva con limit, y pagination indica cuántos pedidos coinciden y si hay otra página.

    Solicitud GET /esims/bookings
    curl 'https://api.fx-port.com/api/v1/esims/bookings?limit=1' \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
    Respuesta 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 El código de estado es 200
    • PASS $.data tiene 1 elemento
    • PASS $.pagination.has_more es igual a true

    Referencia de GET /esims/bookings en la documentación

  3. Comprobar la titularidad

    La comprobación de titularidad responde is_owner verdadero cuando la reserva pertenece a tu agencia. Una reserva de otra agencia y una que no existe reciben la misma respuesta, así que la llamada no sirve para descubrir referencias.

    Solicitud 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"
    Respuesta 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 El código de estado es 200
    • PASS $.is_owner es igual a true

    Referencia de GET /esims/bookings/{booking_id}/verify en la documentación

  4. Consumo masivo

    Una sola llamada lee el consumo de varias eSIM indicadas en iccids y devuelve una entrada por ICCID, cada una con su propio status. Envía siempre iccids.

    Solicitud GET /esims/usage/bulk
    curl 'https://api.fx-port.com/api/v1/esims/usage/bulk?iccids=8900000540463077957' \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
    Respuesta 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 El código de estado es 200
    • PASS $.data[0].status es igual a success

    Referencia de GET /esims/usage/bulk en la documentación

Fallos y cómo reaccionar a cada uno

Todos los fallos comparten un mismo cuerpo, y la primera entrada de errors tiene un code estable. Estas llamadas de pedido fallan a propósito, cada una por un motivo distinto y con una reacción distinta.

  1. Clave de lectura en un pedido

    Una clave de lectura en la llamada de pedido se rechaza con 403 y read_write_permission_required, antes de leer el cuerpo. Cambia a una clave de lectura y escritura.

    Solicitud 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"
}'
    Respuesta 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 El código de estado es 403
    • PASS El código de error es read_write_permission_required
    • PASS $.errors[0].type es igual a permission_error

    Referencia de POST /esims/orders en la documentación

  2. Correo no válido

    Un valor que no es una dirección de correo se rechaza con 400 y invalid_email, y field indica email. Corrige el valor antes de volver a enviar el pedido: la misma solicitud falla del mismo modo.

    Solicitud 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"
}'
    Respuesta 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 El código de estado es 400
    • PASS El código de error es invalid_email
    • PASS $.errors[0].field es igual a email

    Referencia de POST /esims/orders en la documentación

  3. Pedido duplicado

    Un pedido de un paquete que ya se está procesando se rechaza con 409 y duplicate_request. No lo vuelvas a enviar enseguida: busca primero la reserva y vuelve a pedir solo si no se creó ninguna.

    Solicitud 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"
}'
    Respuesta 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 El código de estado es 409
    • PASS El código de error es duplicate_request
    • PASS $.errors[0].type es igual a conflict

    Referencia de POST /esims/orders en la documentación

  4. Demasiadas solicitudes

    Al superar el límite por minuto, la llamada se rechaza con 429 y rate_limit_exceeded, y la cabecera Retry-After indica cuántos segundos esperar. Después reintenta con retroceso.

    Solicitud 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"
}'
    Respuesta 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 El código de estado es 429
    • PASS El código de error es rate_limit_exceeded
    • PASS La cabecera Retry-After está presente
    • PASS $.errors[0].details.retry_after es igual a 12

    Referencia de POST /esims/orders en la documentación

Del catálogo al viajero conectado en cinco pasos

Una integración es un camino corto: leer el catálogo, crear el pedido, entregar la eSIM al viajero, seguir el consumo y recargar cuando se acaben los datos. Solo el pedido y la recarga cambian algo. Todas las demás llamadas solo leen.

Lee el catálogo de un destino

Lista los paquetes de un país, con precios ya en la moneda de tu agencia, y guarda el package_id del que elija el viajero. Envía siempre country: el catálogo completo es una respuesta enorme y sin paginación. Lee los identificadores de paquete de la respuesta en lugar de fijarlos en el código, porque el catálogo cambia.

  • GET /api/v1/esims/packages

Solicitud

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

Respuesta 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
  }
}

Catálogo de paquetes por país

Crea el pedido

Envía el package_id con el correo electrónico y el teléfono del viajero. Un pedido crea exactamente una eSIM y, en Live, se descuenta de tu saldo de agencia. Guarda el booking_id y el ICCID de la respuesta, porque todas las llamadas posteriores necesitan uno de los dos.

  • POST /api/v1/esims/orders

Solicitud

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

Respuesta 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
}
Qué incluye la respuesta del pedido
CampoQué contiene
booking_id La referencia de FX-Port del pedido. Guárdala para los datos de instalación, la comprobación de titularidad y tus propios registros.
data.iccid El identificador de la eSIM. El consumo, las recargas y las instrucciones de instalación se consultan por ICCID.
data.sim.qrcode data.sim.qrcode_url La cadena de activación que codifica el código QR y un enlace a la imagen del código QR.
data.sim.direct_apple_installation_url data.sim.sharing Un enlace que inicia la instalación en un iPhone y una página para compartir donde el viajero puede abrir la eSIM con su código de acceso. La llamada de datos de instalación añade el enlace para Android.
Los datos de activación son sensibles: muéstralos solo al viajero titular de la eSIM.
Si el proveedor aún no ha devuelto la eSIM, el pedido existe igualmente: el ICCID empieza por PENDING- y los datos estarán disponibles en la llamada de datos de instalación cuando el proveedor los tenga.

Crear un pedido de eSIM

Entrega la eSIM al viajero

La respuesta incluye el código QR y su cadena de activación, así que puedes mostrarlos en tus propias pantallas. FX-Port también pide al proveedor que envíe por correo el código QR y un enlace para compartir a la dirección del viajero, de modo que no tienes que reenviarlo tú. La llamada de datos de instalación devuelve más tarde los mismos datos, con los pasos de instalación.

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

Solicitud

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

Respuesta 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
  }
}

Datos de instalación por reserva o ICCID

Sigue el consumo

Lee los datos restantes y la caducidad de una eSIM por su ICCID. La respuesta se guarda en caché hasta 15 minutos, así que úsala para una pantalla o un aviso, no como contador.

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

Solicitud

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

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

Consumo de eSIM individual y masivo

Recarga cuando se acaben los datos

Lista los paquetes que se pueden añadir a esa eSIM concreta y crea la recarga con uno de ellos. Si la lista está vacía, la eSIM no se puede recargar ahora y el viajero necesita una nueva.

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

Solicitud

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

Respuesta 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
}

Consultar y crear recargas

Precios, comisión y tu saldo

Cada paquete incluye sus campos de importe, calculados en el servidor en la moneda de tu agencia. Un precio enviado en el cuerpo de la solicitud se ignora, de modo que un pedido siempre se crea al precio que calcula el servidor.

Campos de importe de un paquete eSIM
CampoQué contiene
base_price price El precio del paquete antes de tu comisión. No es el importe que se descuenta de tu saldo.
total_price retail_price El precio que cobrar al viajero, con tu comisión incluida.
balance_debit_amount b2b_price Lo que sale de tu saldo de agencia cuando pides el paquete en Live. Léelo, no lo calcules.
agency_commission commission_rate Tu tasa de comisión, como texto y como número. Las reservas devuelven tu comisión como importe.

En el ejemplo del catálogo, el viajero paga 468.84 DZD. Un pedido en Live descuenta de tu saldo 418.60 DZD, y la diferencia, 50.24 DZD, es tu comisión.

La tasa depende de tu agencia

La tasa de comisión llega con cada paquete y no es la misma para todas las agencias. Una agencia corporativa con contrato puede tener una tasa de cero, y entonces el precio total es igual al débito.

Lee los campos, no los reconstruyas

El débito puede ser superior al precio base, porque incluye importes propios de tu agencia. Por eso, lee balance_debit_amount y nunca lo calcules a partir de base_price. La palabra price es el precio base en el catálogo, pero el precio de venta en los pedidos, los paquetes de recarga y los datos de instalación: usa base_price y total_price en todas partes y la ambigüedad desaparece.

Precios en la moneda de tu agencia

Todos los importes ya están convertidos a la moneda de tu agencia, sea cual sea la moneda del proveedor. La respuesta también muestra la moneda del proveedor y el tipo de cambio, así que puedes verificar la conversión por tu cuenta y no necesitas volver a convertir.

Cómo se forman los precios de eSIM

Después de la venta: consumo, recargas y datos de instalación

Una venta no termina con el pedido. Estas llamadas mantienen conectado al viajero y solo funcionan con eSIM que tu agencia pidió en el mismo entorno que tu clave.

Leer el consumo y qué tan reciente es

El consumo devuelve los datos restantes, la asignación, el estado y la caducidad de una eSIM, o de hasta 50 eSIM en una sola llamada. FX-Port guarda la última respuesta hasta 15 minutos para proteger los límites de uso del proveedor, así que una cifra puede tener esa antigüedad. Pasa force=true para volver a preguntar al proveedor, por ejemplo justo después de una recarga. No lo hagas en cada solicitud, porque el proveedor limita la frecuencia con la que se puede leer el consumo. Si el proveedor no puede responder, recibes la última cifra conocida marcada como desactualizada.

Consumo de eSIM individual y masivo

Recargas: pregunta primero, crea después

Una recarga son dos llamadas. Primero lista los paquetes que se pueden añadir a esa eSIM concreta y después crea la recarga con uno de los identificadores devueltos. No reutilices nunca el identificador de paquete del pedido original ni guardes un paquete de recarga para más tarde: pregunta de nuevo cuando el viajero quiera recargar. Una recarga añade datos a la eSIM y no sustituye lo que queda, así que lee el resultado en el consumo con force=true.

Consultar y crear recargas

Cuando una recarga no es posible

Los proveedores eligen qué operadores móviles dan servicio a un país y, en casos poco frecuentes, cambian alguno. La eSIM puede seguir funcionando hasta que caduque, aunque su paquete ya no se pueda recargar. La lista de paquetes de recarga llega vacía. Si un proveedor rechaza una recarga, tu saldo no se toca y el intento se guarda como una reserva fallida. La respuesta es un supplier_error al que puedes reaccionar.

Por qué una recarga puede no estar disponible

Datos de instalación y pasos de instalación

La llamada de datos de instalación devuelve, cuando la necesites, el código QR, los datos de activación, los enlaces de instalación y los pasos de instalación de un pedido. La llamada de instrucciones devuelve los pasos por sistema operativo, en el idioma que pidas. Los pasos son un texto genérico del proveedor, así que muéstralos junto al código QR del pedido. Muestra ambos solo al viajero titular de la eSIM.

Datos de instalación por reserva o ICCID

Reservas, historial de recargas y titularidad

La lista de reservas devuelve los pedidos de eSIM de tu agencia en el entorno de tu clave, del más reciente al más antiguo. Puedes buscar por identificador de reserva, nombre del viajero, correo electrónico, nombre del paquete o ICCID. Las recargas no están en esa lista: léelas con el historial de recargas de una eSIM. Antes de construir un enlace o una pantalla en torno a un identificador de reserva, la comprobación de titularidad te dice si es tuyo. Una reserva de otra agencia y una que no existe reciben la misma respuesta.

Listar y verificar reservas de eSIM

Todos los endpoints de eSIM, con OpenAPI, Postman y ejemplos de código

La API de eSIM tiene 12 endpoints bajo una sola URL base. Cada fila abre la página de referencia de esa llamada, con sus campos de solicitud, respuestas, errores y ejemplos en 9 lenguajes.

Endpoints de la API de eSIM con método, ruta, permiso de la clave y finalidad
EndpointQué haceClave
GET /api/v1/esims/packagesLista los paquetes de un país o región, con precios ya en la moneda de tu agencia. Envía siempre un país: el catálogo completo es enorme y no tiene paginación.Lectura
GET /api/v1/esims/compatible-devicesLos dispositivos que admiten eSIM, para comprobarlo antes de que el viajero compre.Lectura
POST /api/v1/esims/ordersCrea una eSIM a partir de un paquete para un viajero y la aprovisiona en el proveedor. En Live se descuenta de tu saldo de agencia.Lectura+Escritura
GET /api/v1/esims/topup-packages/{iccid}Los paquetes que hoy se pueden añadir a una eSIM concreta. Una lista vacía significa que ahora no se puede recargar.Lectura
POST /api/v1/esims/topupsAñade un paquete de recarga a una eSIM existente. En Live, tu saldo se descuenta solo después de que el proveedor lo acepte.Lectura+Escritura
GET /api/v1/esims/usage/{iccid}Los datos restantes, la asignación, el estado y la caducidad de una eSIM. La respuesta puede tener hasta 15 minutos de antigüedad.Lectura
GET /api/v1/esims/usage/bulkEl consumo de hasta 50 eSIM en una sola llamada, una entrada por ICCID, cada una con su propio estado.Lectura
GET /api/v1/esims/bookingsLos pedidos de eSIM de tu agencia, del más reciente al más antiguo, con búsqueda y paginación. Las recargas no están en esta lista.Lectura
GET /api/v1/esims/bookings/{iccid}/topup-historyLas recargas de una eSIM, de la más reciente a la más antigua. La lista está vacía si la eSIM no tiene ninguna.Lectura
GET /api/v1/esims/bookings/{booking_id}/verifyComprueba que una referencia de reserva pertenece a tu agencia, antes de construir un enlace o una pantalla en torno a ella.Lectura
GET /api/v1/esims/bookings/{booking_id}/setup-instructionsEl código QR, los datos de activación, los enlaces de instalación y los pasos de instalación de un pedido, en JSON.Lectura
GET /api/v1/esims/instructions/{iccid}Instrucciones de instalación paso a paso para un ICCID, por sistema operativo, en el idioma que pidas.Lectura

OpenAPI 3.1

Un solo archivo describe cada endpoint y cada campo. Genera un cliente a partir de él, impórtalo en una herramienta de API o dáselo a un asistente de programación.

Archivo OpenAPI 3.1

Colección Postman

La colección de eSIM cubre los 12 endpoints en carpetas que siguen las fases de una venta. No incluye claves, así que añade las tuyas.

Colección Postman de eSIM

Ejemplos de código en 9 lenguajes

Cada página de referencia muestra su solicitud en cURL, Node.js, Python, PHP, Go, Java, C#, Swift y Kotlin, generada a partir de la descripción OpenAPI. Cada solicitud de eSIM está disponible en todos ellos.

Referencia completa de la API

Documentación para asistentes de IA

llms.txt y llms-full.txt entregan a los asistentes de IA la documentación como texto plano, y cada página de la documentación se puede leer como Markdown añadiendo .md a su dirección.

Índice llms.txt para herramientas de IA

Documentación de la API de eSIM

Pensada para producción: claves, errores, reintentos y caché

Una integración de eSIM se evalúa en producción por la autenticación, los fallos, los reintentos, la caché y los límites de uso. Esto es lo que debes saber de cada uno.

Una URL base, dos tipos de clave

Cada solicitud lleva una clave como token Bearer en la cabecera Authorization. El prefijo indica dónde funciona la clave: fxp_test_ para el sandbox y fxp_live_ para Live. Ambas usan la misma URL base, y cada respuesta JSON indica en environment el entorno del que procede. Las claves pertenecen a tu servidor, nunca a un navegador ni a una aplicación. FX-Port solo guarda un hash de cada clave, así que una clave perdida no se puede volver a mostrar. Un cambio en una clave puede tardar unos minutos en aplicarse.

Entornos y colecciones Postman

Qué clave hace qué llamada

Una clave de lectura puede listar paquetes, comprobar dispositivos, leer el consumo y leer reservas. Crear un pedido o una recarga requiere una clave de lectura y escritura, y una clave de lectura que lo intente recibe read_write_permission_required. Cualquier clave se puede restringir a una lista de direcciones IP, y una llamada desde otra dirección recibe ip_not_allowed. Usa una clave de lectura siempre que el código solo muestre resultados.

Claves y niveles de permiso

Un único formato de error para cualquier fallo

Una llamada fallida devuelve un array errors. Su primera entrada tiene un code estable, un type que indica cómo reaccionar y el field que falla. Comprueba el código, nunca el mensaje. La lista de errores compartida por vuelos, hoteles, eSIM y la cuenta contiene 180 códigos. Cuando el proveedor rechaza un pedido o una recarga, la respuesta es un supplier_error con el estado HTTP del propio proveedor. No se descuenta nada y se guarda una reserva fallida. Justo después de un reinicio, el catálogo y la lista de dispositivos pueden responder 202 con success en false: espera unos segundos y vuelve a preguntar.

La lista completa de códigos de error

Reintentar sin pedir dos veces

FX-Port no tiene clave de idempotencia, así que no hay cabecera Idempotency-Key que enviar. Las lecturas se pueden repetir sin riesgo; crear un pedido o una recarga, no. FX-Port rechaza un duplicado evidente con 409 y duplicate_request: un pedido de un paquete que aún se está procesando. En Live también rechaza el mismo paquete pedido de nuevo en los 60 segundos siguientes al último pedido confirmado de tu agencia, sea cual sea el viajero. Los pedidos suelen responder en unos segundos, pero un proveedor lento puede tardar mucho más. Si una llamada agota el tiempo de espera o se corta la conexión, no vuelvas a enviar el pedido enseguida, porque la eSIM puede existir. Búscala con el parámetro search de la lista de reservas, usando el correo electrónico del viajero, y vuelve a pedir solo si no se creó nada.

Reintentar con seguridad tras un tiempo de espera

Sin webhooks: consulta cuando lo necesites

FX-Port no llama a ninguna URL tuya, ni en el sandbox ni en Live. Un pedido responde con la eSIM, o con un marcador PENDING- mientras el proveedor no la ha devuelto aún. Cualquier otra cosa la pides tú cuando la necesites: los datos de instalación, el consumo o la lista de reservas.

Caché y velocidad

El consumo se guarda hasta 15 minutos y la lista de paquetes de recarga unos pocos minutos, y force=true omite la caché. El catálogo sin filtrar es una respuesta enorme y sin paginación, así que envía country y acepta compresión con Accept-Encoding: gzip. Los títulos de los paquetes llegan en el idioma del parámetro locale; la primera solicitud en un idioma distinto del inglés es más lenta, porque el texto se obtiene entonces y después se guarda en caché.

Límites de uso

Los límites se cuentan por clave y por minuto en dos grupos, y cada respuesta incluye ratelimit-limit y ratelimit-remaining, así que puedes ir más despacio antes de que te rechacen. Tras un 429, espera los segundos indicados en Retry-After y reintenta con retroceso exponencial y jitter. Si una misma clave o agencia ejecuta demasiados pedidos o recargas a la vez, la respuesta puede ser concurrency_limit_exceeded.

Límites de uso de eSIM por clave
Tipo de llamadaPor minuto
Crear pedidos y recargas1,200
Cualquier otro endpoint de eSIM6,000

Por ahora, el tope de pedidos y recargas simultáneos está en modo de observación: se cuenta pero no se aplica, así que todavía no se rechaza nada por su causa, y el registro de cambios anunciará el día en que se aplique. Lee estas cifras como la política actual y no como una promesa. Las claves sandbox tienen los mismos contadores por minuto que las claves Live, así que programa las pruebas de carga en lugar de ejecutarlas en bucle.

Límites de uso por clave

Nombres y versiones

Los campos de solicitud son snake_case, como first_name y agent_id. Las grafías anteriores siguen funcionando: user_id se lee como agent_id y añade una entrada en warnings, mientras que customer_email se acepta como email sin ninguna. Muchas respuestas conservan una clave antigua junto a su gemela en snake_case con el mismo valor, como order_id junto a code, y ?naming=snake devuelve solo claves snake_case. La versión va en la ruta, /api/v1: un cambio incompatible recibiría un prefijo nuevo, mientras que los campos y grafías nuevos son aditivos.

Empieza en el sandbox gratuito y pasa a Live

Todo lo que ves en esta página funciona hoy en el sandbox. Una clave sandbox se obtiene por cuenta propia, es gratis y nunca toca tu saldo real.

  1. 1

    Crea una cuenta

    Regístrate en FX-Port. Las claves de sandbox son gratuitas y las reservas de sandbox no tienen cargos reales.

    Crea tu cuenta de FX-Port

  2. 2

    Crea una clave de sandbox

    En la página de API de tu panel, crea una clave que empiece por fxp_test_. Una clave de lectura puede buscar y consultar; una clave de lectura y escritura también puede crear reservas de prueba.

    Abre la página de API del panel

  3. 3

    Envía tu primera solicitud

    Hay una única URL base y la clave va en la cabecera Authorization como token Bearer. La guía de inicio rápido recorre una primera llamada.

    Lee la guía de inicio rápido de la API

  4. 4

    Pasa a Live cuando estés listo

    Usa una clave fxp_live_. Live funciona cuando tu agencia está aprobada; hasta entonces la API responde 403 agency_not_active. Las reservas reales se pagan con un saldo con fondos.

    Lee cómo funciona el paso a Live

Una primera solicitud al catálogo en cURL. La documentación muestra la misma solicitud en todos los lenguajes compatibles.

Solicitud

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

Inicio rápido: primera llamada sandbox

Qué hace el sandbox

Un pedido en el sandbox crea una eSIM de prueba real en el proveedor, con un código de activación ficticio, por lo que no se puede instalar en un teléfono. No se descuenta nada, y las respuestas lo indican: balanceDebited, transactionCreated y payoutCreated son todos false. Una recarga responde con un saldo de cero. El consumo es estático: una eSIM nueva muestra toda su asignación y el estado ACTIVE. Las reservas del sandbox solo son visibles para las claves sandbox.

eSIM en el sandbox

Qué solo se puede probar en Live

La comprobación de saldo, la de duplicados y el bloqueo de saldo se ejecutan solo en Live. Por eso las respuestas 402 con insufficient_balance, 409 por el mismo paquete pedido de nuevo en menos de 60 segundos y 503 con balance_lock_timeout nunca aparecen en el sandbox. Escribe su gestión a partir de la lista de códigos de error.

La lista completa de códigos de error

Pasar a Live

Las claves Live dependen de la aprobación de la agencia: hasta que tu agencia esté aprobada, una clave Live responde agency_not_active y tu clave sandbox sigue funcionando. Los pedidos Live se pagan con un saldo de agencia con fondos. Pasar a Live cambia la clave, no el código, porque sandbox y Live comparten una misma URL base.

Aprobación necesaria para claves Live

Quién desarrolla con la API de eSIM

Cada perfil se apoya en una parte distinta de las mismas llamadas.

Agencias que venden viajes

Las agencias venden una eSIM junto al vuelo y el hotel. Piden con el correo electrónico del propio viajero, para que el proveedor envíe el código QR y un enlace para compartir, y leen el consumo cuando un viajero lo pide. La tasa de comisión llega con cada paquete, y agent_id registra qué usuario de tu agencia hizo un pedido.

OTA y marketplaces

Los marketplaces construyen primero la página de exploración: un país cada vez, paquetes locales o regionales, las redes y la asignación de datos de cada paquete, y una comprobación del dispositivo antes de que el viajero compre. Una pantalla que lista las eSIM de un viajero puede leer el consumo de hasta 50 de ellas en una sola llamada.

Equipos de tecnología de viajes y corporativos

Los equipos de tecnología de viajes y los departamentos de viajes corporativos crean sus propias herramientas de reserva. Todo lo que necesitan para empezar es público: el archivo OpenAPI, la colección Postman y una documentación en texto plano que un asistente de programación con IA puede leer, de modo que el primer prototipo parte del contrato real.

API de eSIM: preguntas frecuentes

¿Qué es la API de eSIM de FX-Port y para quién es?

Es una API REST con la que una agencia de viajes, una OTA o un revendedor vende eSIM de datos de viaje desde una sola integración. Listas los paquetes de un destino con precios en la moneda de tu agencia y pides uno para un viajero. Entregas al viajero el código QR, consultas el consumo y recargas. Todo es JSON sobre HTTPS, y un archivo OpenAPI describe cada endpoint.

¿Hay un sandbox gratuito y cómo consigo una clave?

Sí. Crea una cuenta de FX-Port, abre la página de API de tu panel y crea una clave sandbox; puedes hacerlo por tu cuenta y sin coste. Un pedido en el sandbox crea una eSIM de prueba con un código de activación ficticio, por lo que no se puede instalar en un teléfono. No se descuenta nada de tu saldo. Sandbox y Live comparten una misma URL base, así que el código que pruebas es el que publicas.

¿Qué hace falta para pasar a Live?

Tu agencia debe estar aprobada para que una clave Live funcione. Hasta entonces se rechaza una clave Live y tu clave sandbox sigue funcionando. Los pedidos Live se pagan con un saldo de agencia con fondos, que el sandbox nunca toca, y cualquier clave se puede restringir a una lista de direcciones IP. Cambiar de entorno consiste solo en cambiar la clave; cada respuesta indica el entorno del que procede.

¿Qué países y paquetes puedo vender?

Hay paquetes para más de 190 países, y los paquetes regionales aparecen bajo su región. Los paquetes se diferencian en datos incluidos, validez, redes y si admiten recarga. Lee estos campos y el identificador del paquete de la respuesta del catálogo en lugar de fijarlos en el código. Consulta un país cada vez, porque el catálogo completo es una respuesta enorme. Una lista de dispositivos aparte permite comprobar el teléfono del viajero antes de la venta.

¿Cómo recibe el viajero la eSIM?

La respuesta del pedido incluye el código QR, su cadena de activación, un enlace de instalación para iPhone y una página para compartir. Puedes mostrarlos en tus propias pantallas. FX-Port también pide al proveedor que envíe por correo el código QR y un enlace para compartir a la dirección del viajero en cuanto se crea la eSIM. Si el proveedor aún no ha devuelto la eSIM, el pedido existe igualmente y los datos estarán disponibles más tarde en la llamada de datos de instalación.

¿Cómo se combinan precios, comisión y saldo?

Cada paquete incluye estos campos de importe en la moneda de tu agencia: el precio base antes de tu comisión, el precio total que cobrar al viajero, el importe descontado de tu saldo y tu tasa de comisión. Tu comisión es el precio total menos el débito. Lee estos campos en lugar de reconstruirlos, porque el débito es propio de tu agencia. En el sandbox no se descuenta nada; en Live, el débito sale de tu saldo de agencia.

¿Puedo recargar una eSIM y cómo veo lo que queda?

Sí, en dos llamadas: lista los paquetes que se pueden añadir a esa eSIM concreta y crea la recarga con uno de ellos. Una recarga no siempre es posible, porque un proveedor puede cambiar el operador de un país. Una lista vacía significa entonces que el viajero necesita una eSIM nueva. El consumo se guarda en caché hasta 15 minutos, así que trátalo como una cifra reciente, y una llamada lee hasta 50 eSIM.

¿Cómo se informa de los fallos y hay webhooks?

Un fallo llega en un único formato con un código de error estable, y ese código es lo que debe comprobar tu programa, no el texto del mensaje. Las lecturas se pueden repetir sin riesgo con retroceso. Crear un pedido o una recarga es distinto: no hay clave de idempotencia, así que tras un tiempo de espera agotado busca la reserva antes de volver a intentarlo. FX-Port rechaza un duplicado evidente, como el mismo paquete pedido dos veces en 60 segundos en Live. No hay webhooks.

¿Puedo cancelar o reembolsar un pedido de eSIM mediante la API?

No. La API no tiene ningún endpoint para cancelar ni reembolsar un pedido de eSIM. Cada pedido crea exactamente una eSIM, así que comprueba el paquete y los datos del viajero antes de enviarlo. Si el proveedor rechaza un pedido, no se descuenta nada y se guarda una reserva fallida. Para un problema con un pedido concreto, escribe al equipo de desarrollo e indica su identificador de reserva.

¿Qué necesito para empezar y qué herramientas ayudan?

Necesitas una clave sandbox y un cliente HTTP. La documentación añade un archivo OpenAPI 3.1, una colección Postman, ejemplos de código en 9 lenguajes y exportaciones en texto plano para asistentes de IA. Guarda tus claves en tu servidor, nunca en un navegador ni en una aplicación. Lo que lleva más tiempo es tu propio proceso de compra, la entrega del código QR al viajero y la gestión de errores.

Otras APIs de FX-Port

Una eSIM suele acompañar a un viaje. Las APIs de vuelos y de hoteles usan las mismas claves, el mismo cuerpo de error y las mismas convenciones que las de eSIM, y sus reservas están en el mismo historial de la cuenta.

  • API de vuelos

    Busca, tarifica y reserva vuelos, paga pedidos retenidos, cancela y consulta billetes.

  • API de hoteles

    Encuentra hoteles, consulta tarifas, haz prerreservas y reservas, consulta vouchers y cancela.

  • API de trasladosPreliminar

    Cotiza, reserva, sigue y cancela traslados de aeropuerto.

¿Prefieres no escribir código? Las agencias también pueden vender eSIM desde el panel de FX-Port. Vende eSIM desde el panel

Haz tu primer pedido de eSIM en el sandbox

Crea una cuenta, genera una clave sandbox, lista paquetes, crea un pedido y consulta el consumo hoy mismo. Las claves Live llegan cuando tu agencia esté aprobada.

Crear tu cuentaEnviar un correo al equipo de desarrollo

Pregunta a un asistente de IA sobre esta API

Abre esta página en un asistente y pide un plan de integración paso a paso.

FX-PORT

Tu plataforma de distribución de viajes B2B de confianza. Accede a inventario global y crece tu negocio con mejores tarifas y herramientas fáciles.

  • Términos
  • Privacidad
  • Contáctanos
  • Corporativo
  • Blog
  • API Vuelos B2B
  • API Traslados B2B
  • API Ferries B2B
  • API Hoteles B2B
  • B2B eSIM API
  • Bed Bank B2B
  • Consolidador Vuelos B2B
  • Aerolíneas
  • Aeropuertos
  • Países
  • eSIMs

Servicios de Vuelos

FX-Port es una plataforma de distribución de vuelos B2B completa que permite a las agencias de viajes acceder y vender boletos de avión en todo el mundo. Con conexiones a más de 500 aerolíneas, las agencias pueden ofrecer tarifas al por mayor competitivas con confirmaciones instantáneas y emisión de boletos automatizada.

Nuestra plataforma ofrece disponibilidad en tiempo real, herramientas de comparación de precios y gestión de reservas automatizada. Las agencias de viajes pueden acceder a tarifas aéreas B2B exclusivas, gestionar comisiones y optimizar sus operaciones de vuelo a través de nuestro sistema integrado.

Servicios de Alojamiento

Accede a nuestra extensa red de más de 1.5 millones de propiedades en todo el mundo a través de nuestra plataforma de reservas de hoteles B2B. Las agencias de viajes pueden ofrecer tarifas competitivas con márgenes garantizados y confirmaciones de habitaciones instantáneas en todas las categorías de alojamiento.

Desde resorts de lujo hasta opciones económicas, nuestra plataforma proporciona información completa de las propiedades, precios dinámicos y gestión de reservas automatizada para una distribución de hoteles sin problemas.

Soluciones de Viajes

Servicios de transferencia completos con una red global de proveedores verificados, ofreciendo transferencias aeropuerto, tours por la ciudad y servicios de chófer profesional. Nuestro sistema de reservas de ferries conecta rutas marítimas principales con capacidades de reserva instantánea y tarifas B2B competitivas.

Paquetes de Umrah especializados con servicios completos que incluyen procesamiento de visas, alojamiento y transporte. Paquetes de viajes personalizados con precios dinámicos y gestión de inventario automatizada para agencias de viajes.

FX-Port revoluciona la distribución de viajes B2B con tecnología de vanguardia y soluciones completas. Nuestra plataforma permite a las agencias de viajes acceder a inventario global, gestionar reservas de manera eficiente y crecer su negocio con tarifas competitivas y herramientas automatizadas.

Con soporte para múltiples monedas, procesamiento de pagos locales y servicio al cliente 24/7, aseguramos operaciones sin problemas para agencias de viajes en todo el mundo. Nuestra plataforma ofrece disponibilidad en tiempo real, confirmaciones instantáneas y herramientas de gestión de reservas completas.

Las agencias de viajes pueden aprovechar nuestra plataforma para ofrecer una gama completa de servicios de viajes, incluyendo reservas de vuelos, reservas de hoteles, servicios de transferencia, boletos de ferry, paquetes de Umrah y experiencias de viaje personalizadas. Nuestro mercado B2B conecta a las agencias con proveedores verificados en todo el mundo.

FX-Port proporciona seguridad de nivel empresarial, gestión de comisiones automatizada y análisis detallados para el crecimiento del negocio. Únete a cientos de agencias exitosas que utilizan nuestra plataforma para optimizar sus operaciones y expandir su presencia en el mercado.

© 2026 FX-PORT. Todos los derechos reservados.

Ir al contenido
FX-Port para proveedoresVuelos—Aerolíneas·Consolidadores·OTAs·Agencias GDSHoteles—Bed banks·PMS/CMS·HotelesTodos los proveedores de viajes
CorporativoAPI
Iniciar Sesión
Obtén acceso ahora
Panel de control