
I partner possono usare la stessa API eSIM di Atli su cui si basano heyatli.com e il widget di Atli. Puoi creare le tue interfacce per l’elenco delle destinazioni, la scelta dei piani, il checkout e l’installazione in un sito, un’app o un bot. Atli fornisce il catalogo dei piani, elabora i pagamenti tramite il proprio account Stripe ed emette le eSIM.
L’API non usa chiavi API a livello di applicazione. L’autenticazione avviene tramite token individuali di ciascun utente. Il tuo server fa accedere ogni utente con un ID dispositivo univoco o tramite OAuth, poi invia le richieste all’API a suo nome. Ogni account ospite richiede il proprio ID dispositivo, che la tua applicazione deve conservare in modo sicuro.
Sandbox, produzione e file OpenAPI
| Sandbox | Produzione | |
|---|---|---|
| API | https://api-staging.heyatli.com | https://api.heyatli.com |
| File OpenAPI | https://api-staging.heyatli.com/openapi.yaml | https://api.heyatli.com/openapi.yaml |
| Pagina di pagamento | https://staging.heyatli.com/pay | https://heyatli.com/pay |
La Sandbox usa account separati e pagamenti di prova, e non effettua addebiti reali. Le sue eSIM vengono da un operatore di test, quindi non si possono installare su un telefono, e le vendite in Sandbox non generano mai commissioni. Tutti gli esempi di questa guida che creano account o ordini usano gli endpoint della Sandbox. Per la produzione, cambia l’URL di base dell’API in https://api.heyatli.com. La documentazione su partners.heyatli.com/it/dev/api permette di passare dall’una all’altra.

Gli errori dell’API seguono sempre lo stesso formato: un code, un message in inglese e un trace_id per la risoluzione dei problemi con l’assistenza Atli. Usa code per stabilire come la tua applicazione gestisce l’errore e quale messaggio mostra. Il campo message può essere conservato nei tuoi log.
Accesso, preventivi, riscatto dei voucher e sincronizzazione delle eSIM sono soggetti a rate limit, e una richiesta rifiutata risponde 429 con Retry-After in secondi.
Puoi generare un client tipizzato per l’API dalla specifica OpenAPI invece di scrivere le singole richieste 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-sdkAl posto di typescript-fetch puoi usare python, java, csharp, php o swift6. Per Go serve go --additional-properties=enumClassPrefix=true.
Passaggio 1: crea un utente
Puoi creare un account ospite Atli per ogni utente senza richiedere la registrazione. Genera un UUID univoco per ogni utente (per esempio con crypto.randomUUID()) e salvalo in modo sicuro nel record del suo account.
Tratta l’ID dispositivo come una credenziale riservata, perché chiunque vi abbia accesso può autenticarsi come quell’utente.
Usalo per accedere dal tuo server. Un ID che Atli non ha mai visto crea un account ospite, mentre un ID già noto fa rientrare nello stesso account:
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 }
}Invia token come Authorization: Bearer YOUR_TOKEN in ogni chiamata che richiede un utente. Dura 15 minuti. Rinnovalo poco prima della scadenza con POST /refresh e il refresh_token. Nella risposta del refresh il nuovo token non si chiama token ma access_token. Assicurati che la tua integrazione legga il campo corretto per evitare errori di autenticazione quando scade il token iniziale. Salva il refresh token ogni volta, perché ogni refresh ne restituisce uno nuovo e invalida quello vecchio. Se li perdi entrambi, accedi di nuovo con l’ID dispositivo.
Un ospite può comprare e usare eSIM. Alcune eSIM condivise e alcuni voucher richiedono un account completo, e l’API li rifiuta a un ospite con un codice come gift_sign_in_required. Per dare un’email all’ospite, invia il suo token e il suo device_id a POST /auth/email/otp, poi conferma con POST /auth/email/verify. Allo stesso modo l’accesso con WhatsApp o Telegram può trasformare un ospite in un account completo. In entrambi i casi l’ospite conserva le eSIM e i dati dell’account che ha già. Se ometti il device_id, o usi un’email che ha già un account Atli, la persona finisce in un account diverso.
Passaggio 2: associa l’utente al tuo codice partner
Associa ogni nuovo utente al tuo codice prima del suo primo preventivo:
curl https://api-staging.heyatli.com/user/referral/redeem \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "code": "YOUR_PARTNER_CODE" }'Il campo result indica l’esito: ok significa che l’utente è stato associato correttamente, already che ha già un referrer, notnew che ha già effettuato un acquisto, own che si tratta del tuo stesso codice e notfound che il codice non è stato trovato. Si può associare una persona una sola volta, e solo se non ha un referrer né acquisti precedenti. Fai questa chiamata subito dopo aver creato l’utente.
L’associazione è permanente. Se il tuo codice prevede uno sconto, si applica alla prima eSIM dell’utente senza che tu debba inviare di nuovo il codice. La guida al programma di affiliazione spiega quanto ti rende l’associazione.
Passaggio 3: mostra i piani e chiedi un preventivo
GET /explore/plans restituisce il catalogo completo, che comprende le destinazioni disponibili, i pacchetti, i prezzi e il traffico dati incluso. Non richiede token, quindi il tuo server può elencare i piani prima che qualcuno abbia un account. Chiamalo dal tuo server, perché l’API rifiuta con 403 le richieste dal browser che arrivano da altri siti. Passa currency e filtra con destination (JP, europe) o category (local, regional, global):
curl 'https://api-staging.heyatli.com/explore/plans?currency=EUR&destination=JP'Il campo id di un pacchetto è il product_id che acquisti. Chiedine il preventivo con store: true per ottenere un 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": "…"
}Mostra net_total_cents come prezzo finale. I preventivi salvati scadono dopo 30 minuti, quindi genera il preventivo quando l’utente passa al checkout. Ogni utente ha un solo preventivo salvato alla volta, e uno nuovo sostituisce il precedente.
target_esim_id ricarica una eSIM che l’utente ha già. Se manca, il piano va sulla eSIM predefinita dell’utente. Se non ha ancora una eSIM, o se la rete di quella predefinita non vende quel piano, il piano va su una eSIM nuova. Per chi ha fatto l’accesso con il proprio account Atli, il campo new_esim del preventivo indica quale dei due casi vale. I preventivi degli ospiti non lo includono. Per un ospite, confronta la eSIM dell’ordine completato con quelle elencate da GET /esims prima di mostrare i passaggi di installazione.
auto_apply_best_voucher applica il voucher valido di valore più alto tra quelli dell’utente, mentre points_to_redeem gli permette di riscattare i suoi punti, che le app di Atli mostrano come crediti Atli. Un ordine accetta un solo tipo di sconto. Lo sconto referral del tuo link ha la precedenza e batte qualsiasi voucher che il preventivo sceglierebbe da solo. Un voucher indicato con voucher_code lo sostituisce, e indicare sia un voucher sia un referral_code fa fallire la richiesta con cannot_combine_voucher_and_referral. I punti contano solo quando non si applica nessuno dei due.
Passaggio 4: crea l’ordine e incassa il pagamento
Acquista il preventivo salvato tramite il suo quote_id. L’ordine prende piano, sconti e prezzo dal preventivo. Se nel frattempo il totale è cambiato di oltre l'1%, l’acquisto fallisce con price_changed e devi chiedere un nuovo preventivo.
Ogni preventivo può essere usato per un solo ordine. Se una richiesta di acquisto viene inviata di nuovo per errore o dopo un timeout, l’API restituisce l’ordine esistente invece di crearne un duplicato. La richiesta deve contenere anche una idempotency_key, che evita ordini duplicati quando acquisti direttamente con un product_id invece che con un preventivo salvato.
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"
}Il client_secret appartiene a un PaymentIntent di Stripe sull’account di Atli. Usalo per montare il Payment Element di Stripe. Il tuo server legge la chiave pubblicabile da GET /stripe/config e la passa alla pagina insieme al client_secret. Non scrivere la chiave nel codice, perché cambia tra Sandbox e produzione, e non leggerla dalla pagina, perché l’API rifiuta le richieste dal browser che arrivano da altri siti:
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',
});Passa il client_secret solo alla sessione dell’utente che sta pagando e tienilo fuori dai log. Quando Stripe conferma il pagamento, chiedi ad Atli di emettere la 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 quella chiamata fallisce, non addebitare di nuovo. Atli completa in automatico un ordine pagato.
Il pagamento viene addebitato sull’account Stripe di Atli, quindi sull’estratto conto del tuo cliente compare il nome di Atli e rimborsi e contestazioni vanno ad Atli. Per offrire Apple Pay e Google Pay nel tuo modulo, scrivi a [email protected] quando la tua integrazione ha alle spalle vendite reali. Le carte salvate funzionano con la stessa chiamata di acquisto: aggiungi payment_method_id per addebitarne una, oppure save_card: true per conservare una carta nuova per la prossima volta.
Usare la pagina di pagamento di Atli
I bot WhatsApp e Telegram, le app vocali e gli assistenti AI non possono mostrare il modulo di pagamento di Stripe. Per queste integrazioni puoi indirizzare gli utenti alla pagina di pagamento ospitata da Atli. Costruisci il link con i tre valori sigillati restituiti dall’acquisto. Se l’acquisto restituisce anche options e options_signature, passali, e la pagina mostra sopra il modulo della carta una riga come «Plan for Japan» nella lingua indicata nella tua richiesta:
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();La pagina di pagamento mostra il totale dell’ordine e accetta pagamenti con carta, Apple Pay e Google Pay. Poi chiama POST /plan/fulfill-payment con l’order_id e ripeti la chiamata finché l’ordine non risulta pagato. Solo quella chiamata conferma il pagamento, perché la pagina mostra come riuscito anche un pagamento ancora in elaborazione.
Rispetta questi requisiti quando generi i link di pagamento:
- Passa
sealed_secret,key_id,seal_signatureeoptions_signatureesattamente come li ha restituiti l’API, e alla codifica pensaURLSearchParams.optionsè l’eccezione: codificalo in base64url senza prima modificare il JSON. Non mettere mai unclient_secretin chiaro in un link. - I valori della Sandbox si aprono solo su
staging.heyatli.com/paye quelli di produzione solo suheyatli.com/pay. - Il link paga l’ordine di qualcuno. Mandalo solo al titolare dell’account e tienilo fuori dai log.
- Non salvare i link per dopo. Un nuovo acquisto annulla l’ordine in sospeso precedente e il suo link.
brand=nonenasconde il logo di Atli.langethemeimpostano la lingua e l’aspetto della pagina. I parametri di reindirizzamento accettano solo indirizzihttpssu heyatli.com o sui suoi sottodomini, quindi di’ alla persona di tornare nella tua chat dopo aver pagato.- Il pulsante di annullamento della pagina lascia aperto l’ordine. Per annullarlo, chiama
POST /orders/{id}/cancel.
La stessa pagina serve anche a salvare una carta senza pagare: crea il setup con POST /user/payment-methods/setup-intent, costruisci il link con type impostato su setup_intent, poi salva la carta con POST /user/payment-methods/confirm. Su partners.heyatli.com/it/dev/payment-widget puoi aprire un pagamento di prova su un ospite Sandbox appena creato.
Passaggio 5: mostra la eSIM e i link di installazione
Una eSIM potrebbe non essere disponibile per l’installazione subito dopo il pagamento. Controlla lo stato dell’ordine finché l’oggetto esim non contiene i dettagli di installazione. Mentre l’ordine è in elaborazione, mostra un messaggio di stato adeguato:
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": "…"
}
}Lo stato paid conferma il pagamento, mentre completed indica che la eSIM e il piano associato sono stati predisposti. Trasforma qr_string in un codice QR per l’installazione da un secondo dispositivo. Per gli utenti che installano la eSIM direttamente sul telefono, fornisci i link di installazione per iPhone o Android, che aprono la configurazione eSIM del telefono:
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}`;Oppure dai al tuo utente un solo link che fa tutto: https://heyatli.com/my/esim con lpa uguale al qr_string in base64url e iccid uguale all’ICCID della eSIM. La pagina mostra il codice QR, entrambi i link da un tocco e i dati per l’installazione manuale, e con l’ICCID mostra anche i piani e il traffico dati rimasto. Non serve un account Atli. Metti una lingua nel percorso, per esempio /ja/my/esim, e usa staging.heyatli.com per una eSIM della Sandbox. Chiunque abbia il link può installare la eSIM, quindi mandalo solo alla persona che la userà.
Le nostre guide per iPhone e Android mostrano cosa vede poi l’utente.
GET /esims elenca le eSIM dell’utente con i dettagli di installazione, i piani e il traffico consumato fino all’ultima sincronizzazione. POST /esims/{id}/sync chiede alla rete i valori aggiornati. Ogni richiesta di sincronizzazione contatta l’operatore di rete ed è soggetta a rate limit. Chiedi i dati di consumo aggiornati quando servono, invece di interrogare l’API automaticamente a intervalli fissi.
Far accedere le persone con il loro account Atli
Per un’app in cui le persone usano il proprio account Atli invece di un account ospite, Atli supporta OAuth 2.1: il flusso authorization code con PKCE (S256), refresh token a rotazione e revoca. Gli utenti si autenticano e autorizzano l’accesso su heyatli.com, quindi la tua applicazione non gestisce mai le loro password Atli.
Registra un client su partners.heyatli.com/it/dev/oauth/clients. Un account può avere fino a 10 client: quelli public per app su telefono e quelli confidential per un server in grado di custodire un segreto. Una pagina web non può fare da sola la chiamata per il token, perché l’API rifiuta le richieste dal browser che arrivano da altri siti a meno che Atli non abbia segnato il client come attendibile, quindi a un’app web servono un server e un client confidenziale. Solo un client di tua proprietà può ottenere token per l’API, e per possederne uno il tuo account deve avere un indirizzo email.
Recupera gli endpoint OAuth dai metadati del server di autorizzazione invece di scriverli nel codice:
curl https://api.heyatli.com/.well-known/oauth-authorization-serverGli access token durano 15 minuti. Ogni operazione di refresh restituisce un nuovo refresh token, che deve sostituire quello precedente nell’archivio sicuro della tua applicazione. Chi accede tramite il tuo client può essere associato a te in automatico quando Atli attiva questa funzione per il tuo account. Fino ad allora fai tu l’associazione del passaggio 2 con POST /user/referral/redeem e il suo access token.
Condivisione, voucher e gruppi
Per acquistare una eSIM condivisibile, crea un preventivo con is_gift: true e imposta max_claims su un valore compreso tra 1 e 20. Quando l’ordine è evaso, recupera il claim_url da GET /gifts/sent. POST /rewards/voucher/redeem aggiunge un voucher all’account dell’utente. Un membro di un Atli Group può chiedere il preventivo con group_id e comprare con la carta del gruppo. Su partners.heyatli.com/it/dev/api ognuno di questi percorsi è spiegato passo per passo con esempi di codice.
Domande frequenti
L'API di Atli ha una chiave API?
Mi serve un mio account Stripe?
GET /stripe/config, e i dati della carta vanno direttamente a Stripe senza passare né dai tuoi server né dall’API.I clienti possono pagare con Apple Pay o Google Pay?
Come aggiungo dati a una eSIM che l'utente ha già?
target_esim_id impostato su quella eSIM e acquistalo come al solito. Il piano va sulla eSIM che l’utente ha già, quindi non c’è niente di nuovo da installare. Se la rete di quella eSIM non vende il pacchetto, l’API lo rifiuta con incompatible_esim.E se il pagamento va a buon fine ma la chiamata per evadere l'ordine fallisce?
GET /fulfillment/status-updates finché non compare la eSIM.Dove posso fare test senza soldi veri?
api-staging.heyatli.com e si paga con la carta di test di Stripe 4242 4242 4242 4242, una data futura qualsiasi e un codice di sicurezza qualsiasi. La Sandbox ha account propri.


