Checklist da API de eSIM (2026): 12 Funcionalidades que uma API de eSIM de Viagem Deve Ter — e Como Testar Cada Uma

Conectar uma API de eSIM ao seu aplicativo, plataforma de viagens ou motor de reservas não é difícil. O que é difícil é descobrir, após o lançamento, que a API cobra em dobro em caso de timeout, não consegue avisar quando um cliente fica sem dados ou não oferece uma maneira de testar falhas.

Este checklist cobre os 12 recursos que importam em produção e, para cada um deles, como testá-lo antes de você assinar. Usamos a API de Parceiro da TripoSIM como exemplo prático, mas você pode usar o mesmo checklist para comparar qualquer provedor.

1. Autenticação de token segura

O que procurar: Credenciais de cliente OAuth 2.0: você troca um ID de cliente e um segredo por um token de acesso de curta duração. Os segredos nunca viajam com cada requisição.

Como testar: solicite um token e verifique se ele expira. Na API da TripoSIM, o POST /auth/token retorna um token de acesso válido por 15 minutos. Certifique-se de que seu código o atualize automaticamente antes que ele expire.

2. Chaves de idempotência (sem cobranças duplas)

O que procurar: um cabeçalho Idempotency-Key em cada pedido e recarga. Se sua requisição sofrer timeout e você tentar novamente com a mesma chave, a API deve retornar o resultado original em vez de criar um segundo eSIM pago.

Como testar: envie o mesmo pedido duas vezes com a mesma chave e confirme que você recebe apenas um pedido. Em seguida, envie a mesma chave com um corpo diferente — uma boa API irá rejeitá-la. A TripoSIM exige a chave em pedidos de produção e recargas, e retorna 409 IDEMPOTENCY_KEY_REUSED se uma chave for reutilizada com uma requisição diferente.

3. Cotações de preço que bloqueiam o valor

O que procurar: uma maneira de buscar um preço e mantê-lo por um curto período, para que seu cliente pague exatamente o que você mostrou a ele.

Como testar: crie uma cotação, aguarde e depois faça o pedido com ela. As cotações da TripoSIM são válidas por 10 minutos; uma cotação expirada retorna 409 QUOTE_EXPIRED para que você possa refazer a cotação em vez de cobrar um preço surpresa.

4. Um feed de catálogo limpo

O que procurar: um endpoint que liste todos os planos com preço, dados, validade, países de cobertura, 5G, suporte a recarga — e, para planos ilimitados, o limite diário de velocidade total.

Como testar: puxe o catálogo de um país e compare-o com o próprio site do provedor. O endpoint /catalog da TripoSIM retorna JSON ou CSV, inclui planos regionais que cobrem o país e adiciona os campos de uso justo (fup_daily_mb, fup_throttle_kbps) para planos ilimitados. Veja [como funcionam os limites diários ilimitados](/blog/unlimited-esim-daily-limit-by-country-2026).

5. Entrega instantânea de pedido e QR

O que procurar: a resposta do pedido (ou um webhook segundos depois) deve incluir o código de ativação no formato padrão LPA, por exemplo, LPA:1$smdp.example.com$ACTIVATION_CODE, para que você possa mostrar um código QR ou um link de instalação com um toque.

Como testar: faça um pedido no sandbox, gere o QR a partir da string LPA e escaneie-o com a câmera de um telefone para verificar se o formato é válido.

6. Webhooks assinados para cada evento

O que procurar: notificações push para todo o ciclo de vida do eSIM, assinadas para que invasores não possam falsificá-las.

A TripoSIM envia oito tipos de eventos: order.completed, order.failed, esim.activated, esim.usage_80, esim.suspended, esim.resumed, esim.depleted e esim.expired. Cada requisição carrega um cabeçalho X-TripoSIM-Signature — um HMAC-SHA256 do timestamp e do corpo bruto usando seu segredo de assinatura:

<pre><code>// reject requests older than 5 minutes (replay protection) if (Math.floor(Date.now() / 1000) - parseInt(timestamp) &gt; 300) throw new Error('Webhook too old'); const expected = crypto .createHmac('sha256', signingSecret) .update(timestamp + '.' + rawBody) .digest('hex'); if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) { throw new Error('Invalid webhook signature'); }</code></pre>

Como testar: registre um webhook, dispare um pedido e verifique a assinatura em seu código. Em seguida, altere um byte do corpo e certifique-se de que sua verificação o rejeite.

7. Um sandbox que simula todo o ciclo de vida do eSIM

O que procurar: eSIMs reais levam dias para ativar e usar dados. Um bom sandbox permite que você acelere o processo.

Como testar: no sandbox da TripoSIM, use POST /sandbox/esims/{iccid}/simulate com uma ação de activate, usage, deplete, expire ou reset. Cada etapa dispara o webhook correspondente, para que você possa testar seu e-mail de "seus dados estão quase acabando" em minutos, em vez de dias.

8. Simulação de falhas

O que procurar: uma maneira de forçar erros de propósito, para que você saiba que seu aplicativo os gerencia corretamente.

Como testar: envie o cabeçalho X-Sandbox-Simulate com modos como insufficient_balance, price_changed, rate_limit, provider_unavailable ou timeout, e verifique se seu aplicativo mostra uma mensagem clara e tenta novamente apenas quando deve.

9. Recargas no mesmo eSIM

O que procurar: clientes que ficam sem dados devem ser capazes de adicionar mais sem instalar um novo eSIM.

Como testar: chame POST /esims/{iccid}/topup no sandbox (com uma chave de idempotência) e, em seguida, verifique o novo saldo de dados. Verifique também quais planos suportam recargas — o catálogo deve informar isso.

10. Dados de uso e status

O que procurar: um endpoint para dados usados, dados restantes e expiração, para que sua equipe de suporte e seu aplicativo possam responder "quanto de dados eu ainda tenho?".

Como testar: chame GET /esims/{iccid}/usage após um evento de uso simulado. A TripoSIM faz o cache do uso por 5 minutos, portanto, use webhooks (esim.usage_80, esim.depleted) para alertas em tempo real.

11. Suspender e retomar

O que procurar: uma maneira de pausar um eSIM — por exemplo, quando um pagamento é contestado ou um cliente relata um telefone perdido — e retomá-lo mais tarde.

Como testar: suspenda um eSIM de sandbox, confirme que o webhook esim.suspended chega e, em seguida, retome-o e confirme o esim.resumed.

12. Limites de taxa, códigos de erro e changelog claros

O que procurar: limites documentados, códigos de erro que dizem se você deve tentar novamente e um changelog público para que as atualizações nunca te surpreendam.

Como testar: leia a lista de erros e mapeie cada código para "tentar novamente" ou "não tentar novamente" em seu código. A TripoSIM permite 120 requisições por minuto por conta de parceiro (você pode definir limites menores em chaves de API individuais), retorna um cabeçalho Retry-After em respostas 429, marca cada código de erro como passível de repetição ou não, e publica um endpoint de changelog.

Um plano de lançamento simples

1. Dia 1: obtenha as chaves do sandbox, autentique-se e puxe o catálogo.
2. Dia 2: faça pedidos no sandbox com chaves de idempotência e mostre os códigos QR.
3. Dia 3: adicione webhooks, execute os simuladores de ciclo de vida e de falhas.
4. Dia 4: adicione recargas e uso, depois teste em um telefone real com um eSIM ativo.
5. Dia 5: entre no ar.

A maioria das equipes se conecta em menos de uma semana. Leia a [documentação da API](https://docs.triposim.com) completa ou veja nosso [guia de integração de API de eSIM passo a passo](/blog/esim-reseller-api-how-to-integrate-travel-esim-sales-into-your-platform).

Perguntas frequentes

O que uma API de eSIM de viagem deve incluir?

No mínimo: autenticação de token, chaves de idempotência, cotações de preço, um feed de catálogo, códigos QR/ativação instantâneos, webhooks assinados, um sandbox com simuladores de ciclo de vida e falhas, recargas, dados de uso, suspender/retomar e limites de taxa e códigos de erro documentados.

Por que as chaves de idempotência são importantes para uma API de eSIM?

Cada pedido de eSIM custa dinheiro real. Se uma requisição sofrer timeout e seu sistema tentar novamente, uma chave de idempotência garante que a tentativa de reenvio retorne o primeiro resultado em vez de comprar um segundo eSIM.

Como eu testo uma API de eSIM sem comprar eSIMs?

Use o sandbox. Um bom sandbox simula pedidos, ativação, uso de dados, esgotamento e expiração — e permite que você force erros — sem cobrar de sua carteira.

Quanto tempo leva uma integração de API de eSIM?

Com uma API bem documentada e um sandbox completo, a maioria das equipes entra no ar em 3 a 5 dias úteis.

A API da TripoSIM suporta entrega white-label?

Sim. Você recebe o código de ativação e os dados do QR, para que possa entregar o eSIM dentro de seu próprio aplicativo ou e-mails sob sua marca. Veja o [programa de API](/api-program).

Conclusão

O preço importa, mas para uma API de eSIM a verdadeira diferença aparece após o lançamento: tentativas que nunca cobram em dobro, webhooks em que você pode confiar e um sandbox que permite testar tudo primeiro. Execute este checklist em qualquer provedor antes de se comprometer — e [comece com nosso sandbox](/api-program) para ver como a API de Parceiro da TripoSIM se sai.