
Os parceiros podem usar a mesma API de eSIM da Atli que está por trás de heyatli.com e do widget da Atli. Você pode criar as suas próprias interfaces de listagem de destinos, seleção de planos, checkout e instalação para um site, app ou bot. A Atli fornece o catálogo de planos, processa os pagamentos pela conta Stripe dela e emite os eSIMs.
A API não usa chaves de API no nível da aplicação. A autenticação é feita com tokens individuais de cada usuário. O seu servidor faz o login de cada usuário com um ID de dispositivo único ou por OAuth e depois faz as requisições à API em nome dele. Cada conta de convidado exige o próprio ID de dispositivo, que a sua aplicação precisa guardar com segurança.
Sandbox, produção e o arquivo OpenAPI
| Sandbox | Produção | |
|---|---|---|
| API | https://api-staging.heyatli.com | https://api.heyatli.com |
| Arquivo OpenAPI | https://api-staging.heyatli.com/openapi.yaml | https://api.heyatli.com/openapi.yaml |
| Página de pagamento | https://staging.heyatli.com/pay | https://heyatli.com/pay |
O Sandbox usa contas separadas e pagamentos de teste, por isso nenhuma cobrança é real. Os eSIMs dele vêm de uma operadora de teste, então não podem ser instalados num celular, e as vendas no Sandbox nunca rendem comissão. Todos os exemplos deste guia que criam contas ou pedidos usam endpoints do Sandbox. Em produção, troque a URL base da API por https://api.heyatli.com. A referência em partners.heyatli.com/pt/dev/api alterna entre os dois.

Os erros da API seguem sempre o mesmo formato: um code, uma message em inglês e um trace_id para resolver problemas com o suporte da Atli. Use o code para decidir como a sua aplicação trata o erro e qual mensagem mostra. O campo message pode ficar guardado nos seus logs.
Login, cotações, resgate de vouchers e sincronização de eSIM têm limite de requisições, e uma requisição recusada recebe 429 com Retry-After em segundos.
Você pode gerar um cliente tipado da API a partir da especificação OpenAPI em vez de escrever cada requisição HTTP:
docker run --rm -v "$PWD:/out" \
openapitools/openapi-generator-cli generate \
-i https://api.heyatli.com/openapi.yaml \
-g typescript-fetch -o /out/atli-sdkTroque typescript-fetch por python, java, csharp, php ou swift6. Para Go, use go --additional-properties=enumClassPrefix=true.
Passo 1: crie um usuário
Você pode criar uma conta de convidado da Atli para cada usuário sem exigir cadastro. Gere um UUID único para cada usuário, por exemplo com crypto.randomUUID(), e guarde-o com segurança no registro da conta dele.
Trate o ID de dispositivo como uma credencial sensível, porque qualquer pessoa com acesso a ele consegue se autenticar como esse usuário.
Faça o login com ele a partir do seu servidor. Um ID que a Atli nunca viu cria uma conta de convidado, e um ID conhecido volta a entrar na mesma conta:
curl https://api-staging.heyatli.com/login \
-H 'Content-Type: application/json' \
-d '{ "device_id": "YOUR_DEVICE_ID" }'{
"token": "eyJhbGci…",
"refresh_token": "…",
"expires_in": 900,
"session_id": "…",
"user": { "id": "…", "email": null }
}Envie token como Authorization: Bearer YOUR_TOKEN em toda chamada que precisa de um usuário. Ele dura 15 minutos. Renove-o um pouco antes disso com POST /refresh e o refresh_token. Na resposta do refresh, o novo token vem em access_token em vez de token. Garanta que a sua integração leia o campo correto para evitar falhas de autenticação quando o primeiro token expirar. Salve o refresh token toda vez, porque cada refresh devolve um novo e aposenta o antigo. Se você perder os dois, faça login de novo com o ID de dispositivo.
Um convidado pode comprar e usar eSIMs. Alguns eSIMs compartilhados e vouchers exigem uma conta real, e a API os recusa a um convidado com um código como gift_sign_in_required. Para dar um e-mail ao convidado, envie o token e o device_id dele para POST /auth/email/otp e depois confirme com POST /auth/email/verify. O login pelo WhatsApp ou pelo Telegram também transforma um convidado em conta real. Nos dois casos, o convidado mantém os eSIMs e os dados da conta que já tem. Sem o device_id, ou com um e-mail que já tem conta na Atli, a pessoa acaba numa conta diferente.
Passo 2: vincule o usuário ao seu código de parceiro
Vincule cada usuário novo ao seu código antes da primeira cotação:
curl https://api-staging.heyatli.com/user/referral/redeem \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "code": "YOUR_PARTNER_CODE" }'O campo result indica o resultado da chamada: ok significa que o usuário foi vinculado, already significa que ele já foi indicado por alguém, notnew significa que ele já fez uma compra antes, own indica que o código é o seu próprio e notfound significa que o código não foi encontrado. Uma pessoa só pode ser vinculada uma vez, e só se ninguém a tiver indicado antes e ela nunca tiver comprado. Faça essa chamada logo depois de criar o usuário.
O vínculo é permanente. Se o seu código tem desconto, o primeiro eSIM do usuário recebe esse desconto sem que você precise enviar o código de novo. O guia do programa de afiliados explica quanto o vínculo rende.
Passo 3: mostre os planos e peça uma cotação
GET /explore/plans devolve o catálogo completo, que inclui os destinos disponíveis, os pacotes, os preços e as franquias de dados. Não precisa de token, então o seu servidor pode listar planos antes de qualquer pessoa ter conta. Chame-o pelo seu servidor, porque a API recusa com 403 as requisições de navegador vindas de outros sites. Passe currency e filtre com destination (JP, europe) ou category (local, regional, global):
curl 'https://api-staging.heyatli.com/explore/plans?currency=EUR&destination=JP'O id de um pacote é o product_id que você compra. Cote-o com store: true para receber um quote_id:
curl https://api-staging.heyatli.com/plan/quote \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "product_id": "THE_PACKAGE_ID",
"currency": "EUR",
"store": true }'{
"subtotal_cents": 1500,
"total_discount_cents": 150,
"net_total_cents": 1350,
"currency": "EUR",
"quote_id": "…",
"expires_at": "…"
}Mostre net_total_cents como preço final. As cotações armazenadas expiram depois de 30 minutos, então gere a cotação quando o usuário avançar para o checkout. Cada usuário tem uma cotação armazenada por vez, e uma nova substitui a anterior.
target_esim_id recarrega um eSIM que o usuário já tem. Sem ele, o plano vai para o eSIM padrão do usuário. Se ele ainda não tem eSIM, ou se a rede do eSIM padrão não vende esse plano, o plano vai para um eSIM novo. Para quem entrou com a própria conta da Atli, o new_esim da cotação diz qual dos dois casos vale. As cotações de convidados não trazem esse campo. Para um convidado, compare o eSIM do pedido concluído com os que GET /esims lista antes de mostrar os passos de instalação.
auto_apply_best_voucher aplica o voucher elegível de maior valor que o usuário tem, e points_to_redeem permite que ele resgate os pontos, que os apps da Atli mostram como créditos Atli. Um pedido aceita um só tipo de desconto. O desconto de indicação do seu link vem primeiro e passa na frente de qualquer voucher que a cotação escolheria sozinha. Um voucher indicado em voucher_code substitui esse desconto, e indicar ao mesmo tempo um voucher e um referral_code falha com cannot_combine_voucher_and_referral. Os pontos só contam quando nenhum dos dois se aplica.
Passo 4: crie o pedido e receba o pagamento
Compre a cotação armazenada pelo quote_id. O pedido pega o plano, os descontos e o preço da cotação. Se o total tiver mudado mais de 1% desde então, a compra falha com price_changed e você cota de novo.
Cada cotação pode ser usada em um único pedido. Se uma requisição de compra for reenviada por engano ou depois de um timeout, a API devolve o pedido já existente em vez de criar um duplicado. A requisição também precisa incluir uma idempotency_key, que evita pedidos duplicados quando você compra diretamente com um product_id em vez de uma cotação armazenada.
curl https://api-staging.heyatli.com/plan/purchase \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "quote_id": "THE_QUOTE_ID",
"idempotency_key": "A_NEW_UUID" }'{
"order_id": "…",
"client_secret": "pi_…_secret_…",
"sealed_secret": "eyJhbGciOiJFQ0RILUVTIi…",
"key_id": "…",
"seal_signature": "…",
"options": "{\"message\":\"Plan for Japan\",\"lang\":\"en\"}",
"options_signature": "…",
"total_amount_cents": 1350,
"status": "pending_payment"
}O client_secret pertence a um PaymentIntent da Stripe na conta da Atli. Monte o Payment Element da Stripe com ele. O seu servidor lê a chave publicável em GET /stripe/config e a entrega à página junto com o client_secret. Não deixe a chave fixa no código, porque ela muda entre o Sandbox e a produção, e não a busque pela página, porque a API recusa as requisições de navegador vindas de outros sites:
const stripe = Stripe(publishable_key);
const elements = stripe.elements({ clientSecret: order.client_secret });
elements.create('payment').mount('#pay');
const { error } = await stripe.confirmPayment({
elements,
confirmParams: { return_url: window.location.href },
redirect: 'if_required',
});Passe o client_secret só para a sessão do usuário que está pagando e mantenha-o fora dos seus logs. Quando a Stripe confirmar o pagamento, peça à Atli que emita o eSIM:
curl https://api-staging.heyatli.com/plan/fulfill-payment \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "order_id": "THE_ORDER_ID" }'Se essa chamada falhar, não cobre de novo. A Atli conclui sozinha um pedido pago.
O pagamento é cobrado na conta Stripe da Atli, então é o nome da Atli que aparece na fatura do cartão do seu cliente, e reembolsos e contestações ficam com a Atli. Para oferecer Apple Pay e Google Pay no seu próprio formulário, escreva para [email protected] quando a sua integração já tiver vendas reais. Cartões salvos funcionam com essa mesma compra: adicione payment_method_id para cobrar um deles, ou save_card: true para guardar um cartão novo para a próxima vez.
Pagamento na página da Atli
Bots de WhatsApp e de Telegram, apps de voz e assistentes de IA não conseguem mostrar o formulário de pagamento da Stripe. Nessas integrações, você pode direcionar os usuários para a página de pagamento hospedada pela Atli. Monte o link com os três valores selados que a compra devolveu. Quando a compra também devolver options e options_signature, repasse os dois, e a página mostra acima do formulário do cartão uma linha como “Plan for Japan” no idioma que a sua requisição pediu:
const link = new URL('https://staging.heyatli.com/pay');
link.search = new URLSearchParams({
type: 'payment_intent',
sealed_secret: order.sealed_secret,
key_id: order.key_id,
seal_signature: order.seal_signature,
...(order.options && {
options: Buffer.from(order.options).toString('base64url'),
options_signature: order.options_signature,
}),
}).toString();A página de pagamento mostra o total do pedido e aceita cartão, Apple Pay e Google Pay. Depois, chame POST /plan/fulfill-payment com o order_id e repita até o pedido estar pago. Só essa chamada confirma o pagamento, porque a página mostra como sucesso um pagamento que ainda está em processamento.
Siga estes requisitos ao gerar links de pagamento:
- Passe
sealed_secret,key_id,seal_signatureeoptions_signatureexatamente como a API os devolveu, eURLSearchParamscuida da codificação.optionsé a exceção: codifique-o em base64url sem alterar o JSON antes. Nunca coloque umclient_secretpuro num link. - Valores do Sandbox só abrem em
staging.heyatli.com/pay, e valores de produção só abrem emheyatli.com/pay. - O link paga o pedido de alguém. Envie-o só para o dono da conta e mantenha-o fora dos logs.
- Não guarde links para depois. Uma compra nova cancela o pedido pendente anterior e o link dele.
brand=noneesconde o logo da Atli.langethemedefinem o idioma e o visual da página. Os parâmetros de redirecionamento só aceitam endereçoshttpsem heyatli.com ou nos subdomínios dele, então diga à pessoa que volte à sua conversa depois de pagar.- O botão Cancelar da página deixa o pedido aberto. Para cancelá-lo, chame
POST /orders/{id}/cancel.
A mesma página salva um cartão sem pagamento: crie a configuração com POST /user/payment-methods/setup-intent, monte o link com type igual a setup_intent e depois salve o cartão com POST /user/payment-methods/confirm. Em partners.heyatli.com/pt/dev/payment-widget você pode abrir um pagamento de teste com um convidado novo do Sandbox.
Passo 5: mostre o eSIM e os links de instalação
Um eSIM pode não estar disponível para instalação logo após o pagamento. Consulte o status do pedido até que o objeto esim traga os dados de instalação. Enquanto o pedido estiver em processamento, mostre uma mensagem de status adequada:
curl 'https://api-staging.heyatli.com/fulfillment/status-updates?order_id=THE_ORDER_ID' \
-H 'Authorization: Bearer YOUR_TOKEN'{
"order_id": "…",
"status": "completed",
"esim": {
"id": "…",
"iccid": "…",
"lpa_address": "…",
"activation_code": "…",
"qr_string": "…"
}
}O status paid confirma o pagamento, e completed indica que o eSIM e o plano associado a ele foram provisionados. Exiba qr_string como código QR para a instalação a partir de um segundo aparelho. Para usuários que instalam o eSIM diretamente no celular, ofereça os links de instalação para iPhone ou Android, que abrem a configuração de eSIM do próprio aparelho:
const lpa = `LPA:1$${esim.lpa_address}$${esim.activation_code}`;
const carddata = encodeURIComponent(lpa);
const iphone = `https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=${carddata}`;
const android = `https://esimsetup.android.com/esim_qrcode_provisioning?carddata=${carddata}`;Ou entregue ao seu usuário um único link que faz tudo isso: https://heyatli.com/my/esim com lpa igual ao qr_string em base64url e iccid igual ao ICCID do eSIM. A página mostra o código QR, os dois links de um toque e os dados para instalação manual e, se receber o ICCID, mostra também os planos e os dados restantes. Ela não exige conta da Atli. Coloque um idioma no caminho, como /ja/my/esim, e use staging.heyatli.com para um eSIM do Sandbox. Qualquer pessoa com o link consegue instalar o eSIM, então envie-o só para quem vai usá-lo.
Os nossos guias para iPhone e Android mostram o que o usuário vê em seguida.
GET /esims lista os eSIMs do usuário com os dados de instalação, os planos e o consumo de dados até a última sincronização. POST /esims/{id}/sync pede à rede os números atuais. Cada requisição de sincronização consulta a operadora da rede e está sujeita a limite de requisições. Peça dados de consumo atualizados quando for necessário, em vez de consultar automaticamente em intervalos fixos.
Como deixar as pessoas entrarem com a conta da Atli
Para um app em que as pessoas usam a própria conta da Atli em vez de um convidado, a Atli oferece OAuth 2.1: o fluxo de código de autorização com PKCE (S256), refresh tokens rotativos e revogação. Os usuários se autenticam e autorizam o acesso em heyatli.com, então a sua aplicação nunca lida com a senha da conta Atli deles.
Registre um cliente em partners.heyatli.com/pt/dev/oauth/clients. Uma conta pode ter até 10 clientes: public para apps de celular e confidential para um servidor capaz de guardar um segredo. Uma página web não consegue fazer sozinha a chamada de token, porque a API recusa as requisições de navegador vindas de outros sites, a menos que a Atli tenha marcado o cliente como confiável. Por isso, dê a um app web um servidor e um cliente confidencial. Só um cliente seu consegue tokens para a API, e a sua conta precisa de um endereço de e-mail para ter um cliente.
Obtenha os endpoints de OAuth dos metadados do servidor de autorização em vez de fixá-los no código:
curl https://api.heyatli.com/.well-known/oauth-authorization-serverOs access tokens duram 15 minutos. Cada operação de refresh devolve um refresh token novo, que deve substituir o anterior no armazenamento seguro da sua aplicação. Quem entra pelo seu cliente pode ser vinculado a você automaticamente depois que a Atli ativar isso na sua conta. Até lá, vincule essas pessoas você mesmo com POST /user/referral/redeem e o access token delas, como no Passo 2.
Compartilhamento, vouchers e grupos
Para comprar um eSIM compartilhável, crie uma cotação com is_gift: true e defina max_claims com um valor entre 1 e 20. Quando o pedido for concluído, obtenha o claim_url em GET /gifts/sent. POST /rewards/voucher/redeem adiciona um voucher à conta do usuário. Um membro de um Atli Group pode cotar com group_id e comprar no cartão do grupo. A página partners.heyatli.com/pt/dev/api mostra cada uma dessas jornadas passo a passo e com código.
Perguntas frequentes
A API da Atli tem chave de API?
Preciso ter conta própria na Stripe?
GET /stripe/config, e os dados do cartão vão direto para a Stripe sem passar pelos seus servidores nem pela API.Os clientes podem pagar com Apple Pay ou Google Pay?
Como adiciono dados a um eSIM que o usuário já tem?
target_esim_id apontando para esse eSIM e compre como sempre. O plano vai para o eSIM que o usuário já tem, então não há nada novo para instalar. Se a rede desse eSIM não vende o pacote, a API recusa a compra com incompatible_esim.E se o pagamento passar, mas a chamada que emite o eSIM falhar?
GET /fulfillment/status-updates até o eSIM aparecer.Onde testo sem dinheiro de verdade?
api-staging.heyatli.com, com o cartão de teste da Stripe 4242 4242 4242 4242, qualquer data futura e qualquer código de segurança. O Sandbox tem contas próprias.


