Guida

Come integrare l'API eSIM di Atli nel sito o nell'app

Niente chiave API: ogni tuo utente riceve un account ospite Atli. Come associarlo al codice partner, fare il preventivo, incassare e consegnare la eSIM.

Una richiesta curl all'endpoint di acquisto dell'API di Atli accanto a un telefono con la pagina di pagamento di Atli, e la mascotte blu alata di Atli con un telefono in mano vicino a una valigia

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

SandboxProduzione
APIhttps://api-staging.heyatli.comhttps://api.heyatli.com
File OpenAPIhttps://api-staging.heyatli.com/openapi.yamlhttps://api.heyatli.com/openapi.yaml
Pagina di pagamentohttps://staging.heyatli.com/payhttps://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.

La mappa dei percorsi principali dell'API di Atli: creare un utente, ottenere un preventivo, acquistare e pagare, ricevere la eSIM, installarla e controllare i consumi, con rami facoltativi per un account completo, carte salvate e di gruppo, ricariche, sconti e condivisione

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:

Bash
docker run --rm -v "$PWD:/out" \
  openapitools/openapi-generator-cli generate \
  -i https://api.heyatli.com/openapi.yaml \
  -g typescript-fetch -o /out/atli-sdk

Al 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:

Bash
curl https://api-staging.heyatli.com/login \
  -H 'Content-Type: application/json' \
  -d '{ "device_id": "YOUR_DEVICE_ID" }'
JSON
{
  "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:

Bash
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):

Bash
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:

Bash
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 }'
JSON
{
  "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.

Bash
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" }'
JSON
{
  "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:

JavaScript
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:

Bash
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:

JavaScript
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_signature e options_signature esattamente come li ha restituiti l’API, e alla codifica pensa URLSearchParams. options è l’eccezione: codificalo in base64url senza prima modificare il JSON. Non mettere mai un client_secret in chiaro in un link.
  • I valori della Sandbox si aprono solo su staging.heyatli.com/pay e quelli di produzione solo su heyatli.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=none nasconde il logo di Atli. lang e theme impostano la lingua e l’aspetto della pagina. I parametri di reindirizzamento accettano solo indirizzi https su 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.

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:

Bash
curl 'https://api-staging.heyatli.com/fulfillment/status-updates?order_id=THE_ORDER_ID' \
  -H 'Authorization: Bearer YOUR_TOKEN'
JSON
{
  "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:

JavaScript
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:

Bash
curl https://api.heyatli.com/.well-known/oauth-authorization-server

Gli 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?
No. I token identificano una persona e non un’applicazione. Il tuo server fa accedere ogni utente con un ID dispositivo o tramite OAuth, poi chiama l’API a nome di quell’utente.
Mi serve un mio account Stripe?
No. Gli ordini vengono addebitati sull’account Stripe di Atli. Il tuo modulo usa la chiave pubblicabile di Atli presa da 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?
Sì. La pagina di pagamento di Atli li offre entrambi. Per averli in un tuo modulo Stripe, scrivi a [email protected] quando la tua integrazione ha vendite reali.
Come aggiungo dati a una eSIM che l'utente ha già?
Chiedi il preventivo del nuovo pacchetto con 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?
Non addebitare di nuovo. Atli completa in automatico un ordine pagato, quindi continua a interrogare GET /fulfillment/status-updates finché non compare la eSIM.
Dove posso fare test senza soldi veri?
Sulla Sandbox. L’indirizzo è 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.