API de eSIM: guia de integração para provisionar eSIMs

2 de jul. de 2026·8 min de leitura·Por eSIM Tech
Editor de código mostrando uma requisição e uma resposta da API de provisionamento de eSIM

Integrar uma API de eSIM é um dos recursos de maior retorno que um produto de viagem ou telecom pode lançar, porque alguns endpoints transformam o seu checkout em uma loja de conectividade. Este guia cobre a integração completa do ponto de vista do desenvolvedor: provisionamento, entrega, webhooks e os casos extremos que valem a pena tratar.

O fluxo principal

Toda integração de revenda de eSIM se resume a três passos:

1. Customer pays          →  your checkout
2. Provision the eSIM     →  POST /v1/esims
3. Deliver the QR code    →  confirmation page + email

Provisionamento

Quando o pagamento é aprovado, o seu backend faz uma chamada:

curl -X POST https://api.esim.tech/v1/esims \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "product": "local-nl-unlimited",
    "reference": "order_8412"
  }'

A resposta volta na hora, com tudo o que você precisa:

{
  "id": "esim_L4nX...",
  "iccid": "8931089...",
  "lpa": "LPA:1$smdp.esim.tech$K9MX-....",
  "phone_number": "+31612345678",
  "status": "ready",
  "created_at": "2026-07-02T09:41:12Z"
}

O código LPA vem na própria resposta, então não há polling, e-mail ou tarefa assíncrona para esperar. Com cerca de 120 ms de ponta a ponta, dá para chamar de forma síncrona dentro do checkout. Nos produtos de eSIM local, o número de telefone chega na mesma resposta, ou seja, você pode mostrar ao cliente o novo número local antes mesmo de ele escanear o QR code.

Entrega

Gere um QR code a partir do texto LPA (qualquer biblioteca de QR serve; o texto é o conteúdo) e:

  • Mostre-o na página de confirmação
  • Envie-o por e-mail como alternativa (muitas vezes o cliente instala depois, no Wi-Fi)
  • No celular, ofereça também a instalação por universal link, para que quem está no mesmo aparelho não precise de uma segunda tela para escanear

Webhooks de ciclo de vida

Cadastre um endpoint de webhook e você vai receber eventos como:

{ "type": "esim.activated",   "esim": "esim_L4nX", "at": "..." }
{ "type": "usage.threshold",  "esim": "esim_L4nX", "used_mb": 4096, "threshold": 0.8 }
{ "type": "balance.low",      "esim": "esim_L4nX", "remaining_mb": 512 }

Use o evento balance.low para disparar um e-mail de recarga com um clique, que chega ao cliente no momento de maior intenção de compra. Revendedores que automatizam isso costumam ver de 20% a 30% de receita extra por cliente.

Decisões de design que vale acertar

Idempotência. Passe o ID do pedido como reference e repita a chamada com segurança em caso de falha de rede. Assim você nunca provisiona (e paga) dois eSIMs para um mesmo pedido.

Provisione no pagamento, não antes. O eSIM é cobrado quando é provisionado. Não gere eSIMs antecipadamente para carrinhos abandonados.

Guarde o ICCID. É o identificador estável que você vai usar para suporte, recargas e consultas de consumo.

Responda cedo à pergunta “o meu celular aceita isso?”. Verifique a compatibilidade do aparelho com eSIM na sua interface antes do checkout, e não num e-mail de reembolso depois.

Tipos de produto que você pode provisionar

Uma única integração dá acesso ao catálogo completo:

Todos usam o mesmo formato de API. Só o identificador product muda, então ampliar a sua linha depois é uma mudança de configuração, e não um projeto novo. Se você quer avaliar primeiro o lado do negócio, comece por como ser revendedor de eSIM.

Entrando no ar

  1. Crie a sua conta em resellers.esim.tech
  2. Integre o provisionamento e a geração do QR code no ambiente sandbox
  3. Configure o endpoint de webhook (no mínimo, ativação e saldo baixo)
  4. Teste o fluxo de instalação completo em um iPhone e em um Android de verdade
  5. Troque para as chaves de produção e publique

A autenticação é um Bearer token padrão, a API é REST/JSON simples e não há volume mínimo, então o seu primeiro eSIM provisionado já pode ir para um cliente real.

Perguntas frequentes

O que é um código LPA?

O código LPA (Local Profile Assistant) é o texto de ativação que um aparelho compatível com eSIM usa para baixar o seu perfil de SIM. Costuma ser apresentado como QR code. Formato: LPA:1$smdp.example.com$ACTIVATION-CODE. Quando a sua API o devolve na hora, você pode mostrar o QR code direto no fluxo de checkout.

Quão rápido é o provisionamento de eSIM via API?

Na eSIM.tech, uma chamada POST /v1/esims devolve o código LPA e o ICCID em cerca de 120 milissegundos de ponta a ponta, rápido o bastante para provisionar de forma síncrona durante o checkout.

Preciso de conhecimento específico de telecom para integrar uma API de eSIM?

Não. Se você consegue integrar uma API de pagamento, consegue integrar uma API de eSIM. A complexidade de telecom (servidores SM-DP+, acordos com operadoras, geração de perfis) fica escondida atrás da interface REST.

Como o cliente instala o eSIM?

Ele escaneia o QR code que você mostra (ou toca em um universal link no próprio aparelho). O iOS ou o Android então baixa e instala o perfil. Um guia de instalação claro para cada sistema reduz bastante os chamados de suporte.