API de eSIM: guia de integração para provisionar eSIMs
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:
- Dados com pagamento por uso: cobrança por MB, recargas via API, mais de 190 países
- eSIMs locais: número de telefone local de verdade + voz + SMS + dados (ilimitados) em mais de 25 países
- Pacotes de dados na UE: até 500 GB para roteadores, motorhomes e frotas em toda a UE
- Backup 5G: conectividade de failover para locais fixos
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
- Crie a sua conta em resellers.esim.tech
- Integre o provisionamento e a geração do QR code no ambiente sandbox
- Configure o endpoint de webhook (no mínimo, ativação e saldo baixo)
- Teste o fluxo de instalação completo em um iPhone e em um Android de verdade
- 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.
