1. Início
  2. eSIM API

NovoAPI REST com arquivo OpenAPI 3.1

API de eSIM para agências de viagens, OTAs e revendedores

Venda eSIMs de viagem por uma única API REST. Liste pacotes de dados por país com preços na moeda da sua agência, faça o pedido para um viajante, entregue o QR code a ele, acompanhe o consumo e recarregue. Uma URL base atende o sandbox e o Live. Comece com uma chave sandbox grátis; as chaves Live funcionam depois que sua agência for aprovada.

Obter chaves sandbox grátisLer o guia de eSIM

A documentação está escrita em inglês.

URL base
https://api.fx-port.com/api/v1
Autenticação
Authorization: Bearer fxp_test_...
Prefixos das chaves
fxp_test_ / fxp_live_
Endpoints
12
Países com pacotes
190+
Linguagens dos exemplos
9

Nesta página

  • Console
  • Cinco etapas
  • Preços
  • Pós-venda
  • Endpoints
  • Produção
  • Sandbox
  • Quem constrói com ela
  • FAQ
  • APIs relacionadas
  • Começar

A API de eSIM, chamada por chamada

Acompanhe a venda de um eSIM passo a passo, enquanto cada requisição é montada, enviada e respondida. As sessões cobrem a venda de um eSIM, a manutenção da conexão do viajante, a verificação de dispositivos e reservas e as falhas que vale tratar. As requisições e respostas são exemplos da documentação, e esta página nunca chama a API.

3 requisições: Listar os pacotes, Pedir o eSIM, Ler os dados de configuração.

Sessão ilustrativa: os corpos são exemplos da documentação, as datas são adiantadas para ficarem sempre à frente de hoje e os tempos são ilustrativos. Esta página não envia nenhuma requisição.

Baixar a coleção do Postman

Encontrar um pacote, pedir e ler os dados de configuração

Comece com os pacotes de um país, peça um para um viajante e depois leia os dados de configuração do pedido. O sandbox cria um eSIM de teste com um código de ativação fictício e não debita nada, e o console mostra uma cópia reduzida da resposta do catálogo.

  1. Listar os pacotes

    A chamada do catálogo recebe country e type e devolve os pacotes correspondentes, com preços na moeda da sua agência. Guarde o package_id do pacote que o viajante escolher.

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

    Exemplo reduzido para exibição

    • PASS O código de status é 200
    • PASS $.success é igual a true
    • PASS $.data[0].package_id existe
    • PASS $.data[0].balance_debit_amount existe

    Referência de GET /esims/packages na documentação

  2. Pedir o eSIM

    Criar um pedido recebe o package_id com o e-mail e o telefone do viajante. Guarde booking_id e data.iccid da resposta. No sandbox, balanceDebited, transactionCreated e payoutCreated são todos false.

    Requisição 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"
}'
    Resposta 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
}

    Exemplo reduzido para exibição

    • PASS O código de status é 200
    • PASS $.environment é igual a sandbox
    • PASS $.balance_debited é igual a false
    • PASS $.data.iccid existe

    Referência de POST /esims/orders na documentação

  3. Ler os dados de configuração

    A chamada de dados de configuração recebe o booking_id e devolve o QR code, os dados de ativação, os links de instalação e os passos de instalação do pedido. Mostre-os apenas ao viajante dono do eSIM.

    Requisição 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"
    Resposta 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"
  }
}

    Exemplo reduzido para exibição

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

    Referência de GET /esims/bookings/{booking_id}/setup-instructions na documentação

Ler o consumo e depois recarregar

Quando o viajante já tem um eSIM, leia quantos dados restam, pergunte quais pacotes podem ser adicionados a esse eSIM específico e depois crie a recarga. O consumo fica em cache, então um valor pode ter minutos de idade. O histórico de recargas está na barra lateral e na transcrição.

  1. Ler o consumo

    A chamada de consumo recebe o ICCID do pedido e devolve remaining e total em megabytes, o status e a validade. A resposta vem de um cache, e force=true consulta o fornecedor de novo.

    Requisição GET /esims/usage/{iccid}
    curl https://api.fx-port.com/api/v1/esims/usage/8900000540463077957 \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
    Resposta 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 O código de status é 200
    • PASS $.data.data.status é igual a ACTIVE
    • PASS $.data.data.remaining existe

    Referência de GET /esims/usage/{iccid} na documentação

  2. Listar pacotes de recarga

    Esta chamada lista os pacotes que podem ser adicionados hoje a este eSIM específico. Uma lista vazia significa que o eSIM não pode ser recarregado agora. Pegue o package_id da recarga nesta lista, nunca no pedido original.

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

    Exemplo reduzido para exibição

    • PASS O código de status é 200
    • PASS $.data.data tem 2 itens
    • PASS $.data.data[0].type é igual a topup

    Referência de GET /esims/topup-packages/{iccid} na documentação

  3. Criar a recarga

    Criar uma recarga recebe o package_id dessa lista e o ICCID. No Live, o seu saldo só é debitado depois que o fornecedor aceita. No sandbox, o balance da resposta é zero e nada é debitado.

    Requisição 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"
}'
    Resposta 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 O código de status é 200
    • PASS $.environment é igual a sandbox
    • PASS $.balance_debited é igual a false
    • PASS $.data.balance.current é igual a 0

    Referência de POST /esims/topups na documentação

  4. Ler o histórico de recargas

    O histórico de recargas lista as recargas de um eSIM, da mais recente à mais antiga. As recargas não estão na lista de reservas, então é aqui que você as encontra.

    Requisição 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"
    Resposta 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 O código de status é 200
    • PASS $.data[0].type é igual a topup

    Referência de GET /esims/bookings/{iccid}/topup-history na documentação

Verificar um dispositivo e ler as reservas da agência

Antes da venda, confira se o celular do viajante é compatível com eSIM. Depois da venda, leia suas reservas e confira se uma referência de reserva é sua. O consumo em lote está na barra lateral.

  1. Verificar a lista de dispositivos

    A chamada de dispositivos compatíveis devolve os dispositivos com suporte conhecido a eSIM, com brand, model e os. Procure o celular do viajante antes de vender.

    Requisição GET /esims/compatible-devices
    curl https://api.fx-port.com/api/v1/esims/compatible-devices \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
    Resposta 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 O código de status é 200
    • PASS $.success é igual a true
    • PASS $.data[0].model existe

    Referência de GET /esims/compatible-devices na documentação

  2. Listar suas reservas

    A lista de reservas devolve os pedidos de eSIM da sua agência, do mais recente ao mais antigo. Esta requisição pede uma reserva com limit, e pagination informa quantos pedidos correspondem e se há outra página.

    Requisição GET /esims/bookings
    curl 'https://api.fx-port.com/api/v1/esims/bookings?limit=1' \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
    Resposta 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 O código de status é 200
    • PASS $.data tem 1 item
    • PASS $.pagination.has_more é igual a true

    Referência de GET /esims/bookings na documentação

  3. Verificar a titularidade

    A verificação de titularidade responde is_owner verdadeiro quando a reserva pertence à sua agência. Uma reserva de outra agência e uma que não existe recebem a mesma resposta, então a chamada não serve para descobrir referências.

    Requisição 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"
    Resposta 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 O código de status é 200
    • PASS $.is_owner é igual a true

    Referência de GET /esims/bookings/{booking_id}/verify na documentação

  4. Ler o consumo em lote

    Uma chamada lê o consumo de vários eSIMs listados em iccids e devolve uma entrada por ICCID, cada uma com seu próprio status. Envie sempre iccids.

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

    Referência de GET /esims/usage/bulk na documentação

Falhas e como reagir a cada uma

Todas as falhas compartilham um mesmo corpo, e a primeira entrada de errors tem um code estável. Estas chamadas de pedido falham de propósito, cada uma por um motivo e com uma reação diferente.

  1. Chave de leitura em um pedido

    Uma chave de leitura na chamada de pedido é recusada com 403 e read_write_permission_required, antes de o corpo ser lido. Troque por uma chave de leitura + escrita.

    Requisição 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"
}'
    Resposta 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 O código de status é 403
    • PASS O código de erro é read_write_permission_required
    • PASS $.errors[0].type é igual a permission_error

    Referência de POST /esims/orders na documentação

  2. E-mail inválido

    Um valor que não é um e-mail é recusado com 400 e invalid_email, e field indica email. Corrija o valor antes de enviar o pedido de novo: a mesma requisição falha do mesmo jeito.

    Requisição 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"
}'
    Resposta 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 O código de status é 400
    • PASS O código de erro é invalid_email
    • PASS $.errors[0].field é igual a email

    Referência de POST /esims/orders na documentação

  3. Pedido duplicado

    Um pedido de um pacote que já está sendo processado é recusado com 409 e duplicate_request. Não o envie de novo imediatamente: procure primeiro a reserva e peça de novo apenas se nenhuma tiver sido criada.

    Requisição 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"
}'
    Resposta 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 O código de status é 409
    • PASS O código de erro é duplicate_request
    • PASS $.errors[0].type é igual a conflict

    Referência de POST /esims/orders na documentação

  4. Requisições demais

    Acima do limite por minuto, a chamada é recusada com 429 e rate_limit_exceeded, e o cabeçalho Retry-After indica quantos segundos esperar. Depois tente de novo com backoff.

    Requisição 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"
}'
    Resposta 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 O código de status é 429
    • PASS O código de erro é rate_limit_exceeded
    • PASS O cabeçalho Retry-After está presente
    • PASS $.errors[0].details.retry_after é igual a 12

    Referência de POST /esims/orders na documentação

Do catálogo ao viajante conectado em cinco etapas

Uma integração é um caminho curto: ler o catálogo, criar o pedido, entregar o eSIM ao viajante, acompanhar o consumo e recarregar quando os dados acabarem. Só o pedido e a recarga alteram algo. Todas as outras chamadas apenas leem.

Ler o catálogo de um destino

Liste os pacotes de um país, com preços já na moeda da sua agência, e guarde o package_id do pacote que o viajante escolher. Envie sempre country: o catálogo inteiro é uma resposta muito grande e sem paginação. Leia os ids dos pacotes na resposta em vez de fixá-los no código, pois o catálogo muda.

  • GET /api/v1/esims/packages

Requisição

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

Resposta 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 pacotes por país

Criar o pedido

Envie o package_id com o e-mail e o telefone do viajante. Um pedido cria exatamente um eSIM e, no Live, debita o saldo da sua agência. Guarde o booking_id e o ICCID da resposta, pois toda chamada seguinte precisa de um deles.

  • POST /api/v1/esims/orders

Requisição

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

Resposta 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
}
O que a resposta do pedido traz
CampoO que contém
booking_id A referência do pedido na FX-Port. Guarde-a para os dados de configuração, a verificação de titularidade e os seus registros.
data.iccid O identificador do eSIM. Consumo, recargas e instruções de instalação são consultados pelo ICCID.
data.sim.qrcode data.sim.qrcode_url A string de ativação codificada no QR code e um link para a imagem do QR code.
data.sim.direct_apple_installation_url data.sim.sharing Um link que inicia a instalação em um iPhone e uma página de compartilhamento em que o viajante abre o eSIM com o código de acesso. A chamada de dados de configuração acrescenta o link para Android.
Os dados de ativação são sensíveis: mostre-os apenas ao viajante dono do eSIM.
Se o fornecedor ainda não devolveu o eSIM, o pedido existe do mesmo jeito: o ICCID começa com PENDING- e os dados ficam disponíveis na chamada de dados de configuração assim que o fornecedor os tiver.

Criar um pedido de eSIM

Entregar o eSIM ao viajante

A resposta traz o QR code e a sua string de ativação, para você exibi-los nas suas próprias telas. A FX-Port também pede ao fornecedor que envie por e-mail o QR code e um link de compartilhamento ao endereço do viajante, então você não precisa repassá-lo. A chamada de dados de configuração devolve os mesmos dados depois, com os passos de instalação.

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

Requisição

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

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

Dados de configuração por reserva ou ICCID

Acompanhar o consumo

Leia os dados restantes e a validade de um eSIM pelo ICCID. A resposta fica em cache por até 15 minutos; use-a em uma tela ou em um lembrete, não como medidor.

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

Requisição

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

Resposta 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 e em lote

Recarregar quando os dados acabarem

Liste os pacotes que podem ser adicionados a este eSIM específico e crie a recarga com um deles. Se a lista vier vazia, o eSIM não pode ser recarregado agora e o viajante precisa de um novo.

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

Requisição

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

Resposta 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 e criar recargas

Preços, comissão e o seu saldo

Cada pacote traz os seus campos de valores, calculados no servidor na moeda da sua agência. Um preço enviado no corpo da requisição é ignorado, então o pedido sempre é criado ao preço calculado pelo servidor.

Campos de valores de um pacote eSIM
CampoO que contém
base_price price O preço do pacote antes da sua comissão. Não é o valor debitado do seu saldo.
total_price retail_price O preço a cobrar do viajante, com a sua comissão incluída.
balance_debit_amount b2b_price O que sai do saldo da sua agência quando você pede o pacote no Live. Leia o valor, não o calcule.
agency_commission commission_rate A sua taxa de comissão, como texto e como número. As reservas devolvem a sua comissão como um valor.

No exemplo do catálogo, o viajante paga 468.84 DZD. Um pedido no Live debita 418.60 DZD do seu saldo, e a diferença, 50.24 DZD, é a sua comissão.

A taxa pertence à sua agência

A taxa de comissão volta com cada pacote e não é a mesma para todas as agências. Uma agência corporativa contratada pode ter taxa zero e, nesse caso, o preço total é igual ao débito.

Leia os campos, não os refaça

O débito pode ser maior que o preço base, pois valores específicos da sua agência entram nele. Por isso, leia balance_debit_amount e nunca o calcule a partir de base_price. A palavra price é o preço base no catálogo, mas o preço de venda nos pedidos, nos pacotes de recarga e nos dados de configuração: use base_price e total_price em todo lugar e a ambiguidade desaparece.

Preços na moeda da sua agência

Todo valor já vem convertido para a moeda da sua agência, seja qual for a moeda do fornecedor. A resposta também mostra a moeda do fornecedor e a taxa de câmbio, para você conferir a taxa por conta própria e nunca precisar converter de novo.

Como os preços de eSIM são formados

Pós-venda: consumo, recargas e dados de configuração

Uma venda não termina no pedido. Estas chamadas mantêm o viajante conectado e só funcionam em eSIMs que a sua agência pediu no mesmo ambiente da sua chave.

Ler o consumo e saber quão recente ele é

O consumo devolve os dados restantes, a franquia, o status e a validade de um eSIM, ou de até 50 eSIMs em uma chamada. A FX-Port guarda a última resposta por até 15 minutos para proteger os limites de requisições do fornecedor, então um valor pode ter essa idade. Passe force=true para perguntar de novo ao fornecedor, por exemplo logo após uma recarga. Não faça isso a cada requisição, pois o fornecedor limita a frequência de leitura do consumo. Se o fornecedor não puder responder, você recebe o último valor conhecido, marcado como desatualizado.

Consumo de eSIM individual e em lote

Recargas: pergunte primeiro, depois crie

Uma recarga envolve duas chamadas. Primeiro liste os pacotes que podem ser adicionados a este eSIM específico e depois crie a recarga com um dos ids de pacote devolvidos. Nunca reutilize o id do pacote do pedido original e não guarde um pacote de recarga para depois: pergunte de novo quando o viajante quiser recarregar. Uma recarga acrescenta dados ao eSIM e não substitui o que resta, então leia o resultado no consumo com force=true.

Consultar e criar recargas

Quando a recarga não é possível

Os fornecedores escolhem quais operadoras móveis atendem um país e, em casos raros, trocam uma delas. O eSIM pode continuar funcionando até expirar, enquanto o seu pacote não aceita mais recarga. A lista de pacotes de recarga volta vazia. Se um fornecedor rejeitar uma recarga, o seu saldo não é alterado e a tentativa é salva como reserva com falha. A resposta é um supplier_error, ao qual você pode reagir.

Por que uma recarga pode não estar disponível

Dados de configuração e passos de instalação

A chamada de dados de configuração devolve, quando você precisar, o QR code, os dados de ativação, os links de instalação e os passos de instalação de um pedido. A chamada de instruções devolve os passos por sistema operacional, no idioma que você pedir. Os passos são um texto genérico do fornecedor, então mostre-os junto do QR code do pedido. Mostre ambos apenas ao viajante dono do eSIM.

Dados de configuração por reserva ou ICCID

Reservas, histórico de recargas e titularidade

A lista de reservas devolve os pedidos de eSIM da sua agência no ambiente da sua chave, do mais recente ao mais antigo. Você pode pesquisar por id da reserva, nome do viajante, e-mail, nome do pacote ou ICCID. As recargas não estão nessa lista: leia-as no histórico de recargas de um eSIM. Antes de montar um link ou uma tela em torno de um id de reserva, a verificação de titularidade diz se ele é seu. Uma reserva de outra agência e uma que não existe recebem a mesma resposta.

Listar e verificar reservas de eSIM

Todos os endpoints de eSIM, com OpenAPI, Postman e exemplos de código

A API de eSIM tem 12 endpoints sob uma única URL base. Cada linha abre a página de referência da chamada, com seus campos de requisição, respostas, erros e exemplos em 9 linguagens.

Endpoints da API de eSIM com método, caminho, permissão da chave e finalidade
EndpointO que fazChave
GET /api/v1/esims/packagesLista os pacotes de um país ou região, com preços já na moeda da sua agência. Envie sempre um país: o catálogo inteiro é muito grande e não tem paginação.Leitura
GET /api/v1/esims/compatible-devicesOs dispositivos com suporte conhecido a eSIM, para verificar antes de o viajante comprar.Leitura
POST /api/v1/esims/ordersCria um eSIM a partir de um pacote para um viajante e o provisiona no fornecedor. No Live, debita o saldo da sua agência.Leitura + escrita
GET /api/v1/esims/topup-packages/{iccid}Os pacotes que podem ser adicionados hoje a um eSIM específico. Uma lista vazia significa que ele não pode ser recarregado agora.Leitura
POST /api/v1/esims/topupsAdiciona um pacote de recarga a um eSIM existente. No Live, o saldo só é debitado depois que o fornecedor aceita.Leitura + escrita
GET /api/v1/esims/usage/{iccid}Os dados restantes, a franquia, o status e a validade de um eSIM. A resposta pode ter até 15 minutos.Leitura
GET /api/v1/esims/usage/bulkO consumo de até 50 eSIMs em uma chamada, uma entrada por ICCID, cada uma com seu próprio status.Leitura
GET /api/v1/esims/bookingsOs pedidos de eSIM da sua agência, do mais recente ao mais antigo, com pesquisa e paginação. As recargas não estão nesta lista.Leitura
GET /api/v1/esims/bookings/{iccid}/topup-historyAs recargas de um eSIM, da mais recente à mais antiga. A lista fica vazia quando o eSIM não tem nenhuma.Leitura
GET /api/v1/esims/bookings/{booking_id}/verifyConfere se uma referência de reserva pertence à sua agência, antes de montar um link ou uma tela em torno dela.Leitura
GET /api/v1/esims/bookings/{booking_id}/setup-instructionsO QR code, os dados de ativação, os links de instalação e os passos de instalação de um pedido, em JSON.Leitura
GET /api/v1/esims/instructions/{iccid}Instruções de instalação passo a passo para um ICCID, por sistema operacional, no idioma que você pedir.Leitura

OpenAPI 3.1

Um arquivo descreve todos os endpoints e todos os campos. Gere um cliente a partir dele, importe-o em uma ferramenta de API ou entregue-o a um assistente de programação.

Arquivo OpenAPI 3.1

Coleção do Postman

A coleção de eSIM cobre todos os 12 endpoints em pastas que seguem as etapas de uma venda. Ela não contém chaves, então adicione as suas.

Coleção do Postman para eSIM

Exemplos de código em 9 linguagens

Cada página de referência mostra a requisição em cURL, Node.js, Python, PHP, Go, Java, C#, Swift e Kotlin, geradas a partir da descrição OpenAPI. Toda requisição de eSIM está disponível em todas elas.

Referência completa da API

Documentação para assistentes de IA

llms.txt e llms-full.txt entregam a documentação em texto simples aos assistentes de IA, e toda página da documentação pode ser lida em Markdown acrescentando .md ao seu endereço.

Índice llms.txt para ferramentas de IA

Documentação da API de eSIM

Pronta para produção: chaves, erros, novas tentativas e cache

Uma integração de eSIM é avaliada em produção por autenticação, falhas, novas tentativas, cache e limites de requisições. Eis o que saber sobre cada um.

Uma URL base, dois tipos de chave

Toda requisição leva uma chave como bearer token no cabeçalho Authorization. O prefixo indica onde a chave funciona: fxp_test_ para o sandbox e fxp_live_ para o Live. Ambas usam a mesma URL base, e cada resposta JSON informa em environment o ambiente de origem. As chaves ficam no seu servidor, nunca em um navegador ou aplicativo. A FX-Port guarda apenas um hash de cada chave, então uma chave perdida não pode ser exibida de novo. Uma alteração em uma chave pode levar alguns minutos para valer.

Ambientes e coleções do Postman

Qual chave faz qual chamada

Uma chave de leitura pode listar pacotes, verificar dispositivos, ler o consumo e ler reservas. Criar um pedido ou uma recarga exige uma chave de leitura + escrita, e uma chave de leitura que tente isso recebe read_write_permission_required. Qualquer chave pode ser restrita a uma lista de endereços IP, e uma chamada de outro endereço recebe ip_not_allowed. Use uma chave de leitura sempre que o código apenas exibir resultados.

Chaves e níveis de permissão

Um só formato de erro para toda falha

Uma chamada com falha devolve um array errors. A primeira entrada tem um code estável, um type que indica como reagir e o field com problema. Teste o código, nunca a mensagem. A lista de erros compartilhada por voos, hotéis, eSIMs e conta reúne 180 códigos. Quando o fornecedor recusa um pedido ou uma recarga, a resposta é um supplier_error com o status HTTP do próprio fornecedor. Nada é debitado e uma reserva com falha é salva. Logo após uma reinicialização, o catálogo e a lista de dispositivos podem responder 202 com success igual a false: aguarde alguns segundos e pergunte de novo.

A lista completa de códigos de erro

Tentar de novo sem pedir duas vezes

A FX-Port não tem chave de idempotência, então não há cabeçalho Idempotency-Key para enviar. Leituras podem ser repetidas com segurança; criar um pedido ou uma recarga, não. A FX-Port recusa um duplicado óbvio com 409 e duplicate_request: um pedido de um pacote que ainda está sendo processado. No Live, ela também recusa o mesmo pacote pedido de novo em até 60 segundos após o último pedido confirmado da sua agência, seja quem for o viajante. Os pedidos costumam responder em poucos segundos, mas um fornecedor lento pode demorar bem mais. Se uma chamada expirar ou a conexão cair, não envie o pedido de novo imediatamente, pois o eSIM pode existir. Procure-o com o parâmetro search da lista de reservas, usando o e-mail do viajante, e peça de novo apenas se nada tiver sido criado.

Tentar de novo com segurança após um timeout

Sem webhooks: consulte quando precisar

A FX-Port não chama nenhuma URL sua, nem no sandbox nem no Live. Um pedido responde com o eSIM ou com um marcador PENDING- enquanto o fornecedor não o devolveu. Qualquer outra informação você consulta quando precisar: os dados de configuração, o consumo ou a lista de reservas.

Cache e velocidade

O consumo é mantido por até 15 minutos e a lista de pacotes de recarga por alguns minutos, e force=true ignora o cache. O catálogo sem filtro é uma resposta muito grande e sem paginação, então envie country e aceite compressão com Accept-Encoding: gzip. Os títulos dos pacotes voltam no idioma do parâmetro locale; a primeira requisição em um idioma diferente do inglês é mais lenta, porque o texto é buscado nesse momento e depois fica em cache.

Limites de requisições

Os limites são contados por chave e por minuto em dois grupos, e toda resposta traz ratelimit-limit e ratelimit-remaining, para você reduzir o ritmo antes de ser recusado. Após um 429, aguarde os segundos indicados em Retry-After e tente de novo com backoff exponencial e jitter. Pedidos ou recargas demais de uma mesma chave ou agência em execução ao mesmo tempo podem receber concurrency_limit_exceeded.

Limites de requisições de eSIM por chave
Tipo de chamadaPor minuto
Criação de pedidos e recargas1,200
Todos os outros endpoints de eSIM6,000

Por enquanto, o teto de pedidos e recargas em execução ao mesmo tempo está em modo de observação: ele é contado, mas não aplicado, então nada é recusado por causa dele ainda, e o changelog anuncia o dia em que passar a valer. Leia estes números como a política atual, não como uma promessa. As chaves sandbox têm os mesmos contadores por minuto que as chaves Live, então agende testes de carga em vez de executá-los em loop.

Limites de requisições por chave

Nomes e versões

Os campos da requisição são snake_case, como first_name e agent_id. Grafias anteriores ainda funcionam: user_id é lido como agent_id e adiciona uma entrada em warnings, enquanto customer_email é aceito como email sem aviso. Muitas respostas mantêm uma chave antiga ao lado da sua equivalente em snake_case, com o mesmo valor, como order_id ao lado de code, e ?naming=snake devolve apenas chaves em snake_case. A versão fica no caminho, /api/v1: uma mudança incompatível ganharia um novo prefixo, enquanto novos campos e grafias são aditivos.

Comece no sandbox grátis e depois vá para o Live

Tudo nesta página já funciona no sandbox. Uma chave sandbox é de autoatendimento e grátis, e nunca toca no seu saldo real.

  1. 1

    Crie uma conta

    Cadastre-se na FX-Port. As chaves do sandbox são gratuitas e as reservas no sandbox não geram cobranças reais.

    Criar sua conta FX-Port

  2. 2

    Crie uma chave do sandbox

    Na página de API do seu painel, crie uma chave que comece com fxp_test_. Uma chave de leitura pode pesquisar e consultar; uma chave de leitura + escrita também pode criar reservas de teste.

    Abrir a página de API do painel

  3. 3

    Envie sua primeira requisição

    Há uma única URL base, e a chave vai no cabeçalho Authorization como token Bearer. O guia de início rápido percorre a primeira chamada.

    Ler o início rápido da API

  4. 4

    Passe para o Live quando estiver pronto

    Troque pela chave fxp_live_. O Live funciona depois que sua agência for aprovada; até lá, a API responde 403 agency_not_active. As reservas reais são pagas com um saldo com fundos.

    Ler como passar para o Live

Uma primeira requisição de catálogo em cURL. A documentação mostra a mesma requisição em todas as linguagens compatíveis.

Requisição

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

Início rápido: primeira chamada no sandbox

O que o sandbox faz

Um pedido no sandbox cria um eSIM de teste de verdade no fornecedor, com um código de ativação fictício, então ele não pode ser instalado em um celular. Nada é debitado, e as respostas dizem isso: balanceDebited, transactionCreated e payoutCreated são todos false. Uma recarga responde com saldo zero. O consumo é estático: um eSIM novo mostra a franquia completa e o status ACTIVE. As reservas do sandbox só são visíveis para chaves sandbox.

eSIMs no sandbox

O que só o Live pode testar

A verificação de saldo, a verificação de duplicidade e o bloqueio de saldo só rodam no Live. Por isso, as respostas 402 com insufficient_balance, 409 para o mesmo pacote pedido de novo em até 60 segundos e 503 com balance_lock_timeout nunca aparecem no sandbox. Escreva o tratamento delas a partir da lista de códigos de erro.

A lista completa de códigos de erro

Ir para o Live

As chaves Live dependem da aprovação da agência: enquanto a sua agência não for aprovada, uma chave Live responde agency_not_active e a sua chave sandbox continua funcionando. Os pedidos Live são pagos com o saldo abastecido da agência. Ir para o Live muda a chave, não o código, pois sandbox e Live compartilham uma única URL base.

Aprovação exigida para chaves Live

Quem constrói com a API de eSIM

Cada público usa uma parte diferente das mesmas chamadas.

Agências que vendem viagens

As agências vendem um eSIM junto com o voo e o hotel. Elas pedem com o e-mail do próprio viajante, para que o fornecedor envie o QR code e um link de compartilhamento, e consultam o consumo quando um viajante pergunta. A taxa de comissão volta com cada pacote, e agent_id registra qual usuário da sua agência fez um pedido.

OTAs e marketplaces

Os marketplaces constroem primeiro a página de navegação: um país por vez, pacotes locais ou regionais, as redes e a franquia de dados de cada pacote e uma verificação de dispositivo antes de o viajante comprar. Uma tela que lista os eSIMs de um viajante pode ler o consumo de até 50 deles em uma chamada.

Equipes de tecnologia de viagens e corporativas

Equipes de tecnologia de viagens e departamentos de viagens corporativas criam as próprias ferramentas de reserva. Tudo o que precisam para começar é público: o arquivo OpenAPI, a coleção do Postman e uma documentação em texto simples que um assistente de programação com IA consegue ler, de modo que o primeiro protótipo parte do contrato real.

API de eSIM: perguntas frequentes

O que é a API de eSIM da FX-Port e para quem ela serve?

É uma API REST que permite a uma agência de viagens, uma OTA ou um revendedor vender eSIMs de dados para viagem a partir de uma só integração. Você lista os pacotes de um destino com preços na moeda da sua agência e faz o pedido de um deles para um viajante. Você entrega o QR code ao viajante, acompanha o consumo e recarrega. Tudo é JSON sobre HTTPS, e um arquivo OpenAPI descreve cada endpoint.

Existe um sandbox grátis e como consigo uma chave?

Sim. Crie uma conta na FX-Port, abra a página de API do seu painel e crie uma chave sandbox; você mesmo faz isso, sem custo. Um pedido no sandbox cria um eSIM de teste com um código de ativação fictício, então ele não pode ser instalado em um celular. Nada é debitado do seu saldo. Sandbox e Live compartilham uma única URL base, então o código que você testa é o código que vai para produção.

O que é preciso para ir para o Live?

Sua agência precisa estar aprovada para que uma chave Live funcione. Até lá, uma chave Live é recusada e a sua chave sandbox continua funcionando. Os pedidos Live são pagos com o saldo abastecido da agência, que o sandbox nunca toca, e qualquer chave pode ser restrita a uma lista de endereços IP. Migrar significa trocar apenas a chave; cada resposta informa o ambiente de origem.

Quais países e pacotes posso vender?

Há pacotes para mais de 190 países, e os pacotes regionais aparecem sob a sua região. Os pacotes diferem em franquia de dados, validade, redes e na possibilidade de recarga. Leia esses campos e o id do pacote na resposta do catálogo em vez de fixá-los no código. Peça um país por vez, porque o catálogo inteiro é uma resposta muito grande. Uma lista de dispositivos à parte permite verificar o celular do viajante antes da venda.

Como o viajante recebe o eSIM?

A resposta do pedido traz o QR code, a sua string de ativação, um link de instalação para iPhone e uma página de compartilhamento. Você pode exibi-los nas suas próprias telas. A FX-Port também pede ao fornecedor que envie por e-mail o QR code e um link de compartilhamento ao endereço do viajante assim que o eSIM é criado. Se o fornecedor ainda não devolveu o eSIM, o pedido existe do mesmo jeito e os dados ficam disponíveis depois na chamada de dados de configuração.

Como preços, comissão e meu saldo se relacionam?

Cada pacote traz estes campos de valores na moeda da sua agência: o preço base antes da sua comissão, o preço total a cobrar do viajante, o valor debitado do seu saldo e a sua taxa de comissão. Sua comissão é o preço total menos o débito. Leia esses campos em vez de refazê-los, porque o débito é específico da sua agência. No sandbox nada é debitado; no Live, o débito sai do saldo da sua agência.

Posso recarregar um eSIM e como vejo o que resta?

Sim, em duas chamadas: liste os pacotes que podem ser adicionados ao eSIM específico e depois crie a recarga com um deles. Nem sempre a recarga é possível, porque um fornecedor pode trocar a operadora de um país. Uma lista vazia significa então que o viajante precisa de um novo eSIM. O consumo fica em cache por até 15 minutos, então trate-o como um valor recente, e uma chamada lê até 50 eSIMs.

Como as falhas são informadas e há webhooks?

Uma falha volta em um só formato, com um código de erro estável, e é esse código que o seu programa deve testar, não o texto da mensagem. Leituras podem ser repetidas com segurança, usando backoff. Criar um pedido ou uma recarga é diferente: não há chave de idempotência, então, após um timeout, procure a reserva antes de tentar de novo. A FX-Port recusa um duplicado óbvio, como o mesmo pacote pedido duas vezes em até 60 segundos no Live. Não há webhooks.

Posso cancelar ou reembolsar um pedido de eSIM pela API?

Não. A API não tem endpoint para cancelar ou reembolsar um pedido de eSIM. Cada pedido cria exatamente um eSIM, então confira o pacote e os dados do viajante antes de enviá-lo. Se o fornecedor recusar um pedido, nada é debitado e uma reserva com falha é salva. Para um problema com um pedido específico, escreva para a equipe de desenvolvedores e informe o id da reserva.

O que preciso para começar e quais ferramentas ajudam?

Você precisa de uma chave sandbox e de um cliente HTTP. A documentação acrescenta um arquivo OpenAPI 3.1, uma coleção do Postman, exemplos de código em 9 linguagens e exportações em texto simples para assistentes de IA. Mantenha suas chaves no seu servidor, nunca em um navegador ou aplicativo. O que leva mais tempo é o seu próprio checkout, a entrega do QR code ao viajante e o tratamento de erros.

Outras APIs da FX-Port

Um eSIM costuma acompanhar uma viagem. Voos e hotéis usam as mesmas chaves, o mesmo corpo de erro e as mesmas convenções dos eSIMs, e as suas reservas ficam no mesmo histórico da conta.

  • API de Voos

    Pesquise, precifique e reserve voos, pague pedidos retidos, cancele e consulte bilhetes.

  • API de Hotéis

    Encontre hotéis, verifique tarifas, faça pré-reservas e reservas, consulte vouchers e cancele.

  • API de TransferênciasPrévia

    Cote, reserve, acompanhe e cancele transferências de aeroporto.

Prefere não escrever código? As agências também podem vender eSIMs pelo painel da FX-Port. Venda eSIMs pelo painel

Faça seu primeiro pedido de eSIM no sandbox

Crie uma conta, gere uma chave sandbox, liste pacotes, crie um pedido e consulte o consumo hoje mesmo. As chaves Live vêm depois que sua agência for aprovada.

Criar sua contaEscrever à equipe de desenvolvedores

Pergunte a um assistente de IA sobre esta API

Abra esta página em um assistente e peça um plano de integração passo a passo.

FX-PORT

Sua plataforma de distribuição de viagens B2B confiável. Acesse o inventário global e expanda seu negócio com melhores tarifas e ferramentas fáceis.

  • Termos
  • Privacidade
  • Entre em contato
  • Corporativo
  • Blogue
  • API Voos B2B
  • API Transfers B2B
  • API Ferries B2B
  • API Hotéis B2B
  • B2B eSIM API
  • Bed Bank B2B
  • Consolidador Voos B2B
  • Companhias Aéreas
  • Aeroportos
  • Países
  • eSIMs

Serviços de Voo

A FX-Port é uma plataforma de distribuição de voos B2B abrangente que permite que agências de viagens acessem e vendam bilhetes de avião em todo o mundo. Com conexões com mais de 500 companhias aéreas, as agências podem oferecer tarifas de atacado competitivas com confirmações instantâneas e emissão de bilhetes automatizada.

Nossa plataforma oferece disponibilidade em tempo real, ferramentas de comparação de preços e gestão de reservas automatizada. As agências de viagens podem acessar tarifas aéreas exclusivas B2B, gerenciar comissões e simplificar suas operações de voo por meio do nosso sistema integrado.

Serviços de Acomodação

Acesse nossa extensa rede de mais de 1,5 milhão de propriedades em todo o mundo por meio de nossa plataforma de reservas de hotéis B2B. As agências de viagens podem oferecer tarifas competitivas com margens garantidas e confirmações instantâneas de quartos em todas as categorias de acomodação.

De resorts de luxo a opções econômicas, nossa plataforma fornece informações abrangentes sobre propriedades, preços dinâmicos e gestão de reservas automatizada para distribuição de hotéis sem complicações.

Soluções de Viagem

Serviços de transfer abrangentes com uma rede global de fornecedores verificados, oferecendo transferências de aeroporto, passeios pela cidade e serviços de motorista profissional. Nosso sistema de reservas de balsas conecta principais rotas marítimas com capacidades de reserva instantânea e tarifas B2B competitivas.

Pacotes Umrah especializados com serviços completos, incluindo processamento de vistos, acomodação e transporte. Pacotes de viagem personalizados com preços dinâmicos e gestão de inventário automatizada para agências de viagens.

A FX-Port revoluciona a distribuição de viagens B2B com tecnologia de ponta e soluções abrangentes. Nossa plataforma permite que agências de viagens acessem o inventário global, gerenciem reservas de maneira eficiente e expandam seus negócios com tarifas competitivas e ferramentas automatizadas.

Com suporte para múltiplas moedas, processamento de pagamentos locais e atendimento ao cliente 24/7, garantimos operações sem problemas para agências de viagens em todo o mundo. Nossa plataforma possui disponibilidade em tempo real, confirmações instantâneas e ferramentas abrangentes de gestão de reservas.

As agências de viagens podem usar nossa plataforma para oferecer uma gama completa de serviços de viagem, incluindo reservas de voos, reservas de hotéis, serviços de transfer, bilhetes de balsa, pacotes Umrah e experiências de viagem personalizadas. Nosso marketplace B2B conecta agências com fornecedores verificados em todo o mundo.

A FX-Port oferece segurança de nível empresarial, gestão automatizada de comissões e análises detalhadas para o crescimento dos negócios. Junte-se a centenas de agências bem-sucedidas que usam nossa plataforma para simplificar suas operações e expandir sua presença no mercado.

© 2026 FX-PORT. Todos os direitos reservados.

Ir para o conteúdo
FX-Port para fornecedoresVoos—Companhias aéreas·Consolidadores·OTAs·Agências GDSHotéis—Bed banks·PMS/CMS·HotéisTodos os fornecedores de viagens
CorporativoAPI
Login
Obtenha acesso agora
Painel