eSIM API Checklist (2026): 12 funzionalità che un'API per eSIM da viaggio deve avere — e come testarle

Collegare un'API eSIM alla tua app, piattaforma di viaggio o motore di prenotazione non è difficile. Ciò che è difficile è scoprire, dopo il lancio, che l'API effettua doppi addebiti in caso di timeout, non riesce a dirti quando un cliente esaurisce i dati o non ti offre alcun modo per testare i guasti.

Questa checklist copre le 12 funzionalità che contano in produzione e, per ognuna, come testarla prima di iscriverti. Usiamo l'API Partner di TripoSIM come esempio pratico, ma puoi usare la stessa checklist per confrontare qualsiasi fornitore.

1. Autenticazione sicura tramite token

Cosa cercare: Credenziali client OAuth 2.0: scambi un client ID e un secret per un access token a breve durata. I secret non viaggiano mai con ogni richiesta.

Come testare: richiedi un token, poi verifica che scada. Nell'API TripoSIM, POST /auth/token restituisce un access token valido per 15 minuti. Assicurati che il tuo codice lo rinnovi automaticamente prima che scada.

2. Chiavi di idempotenza (niente doppi addebiti)

Cosa cercare: un header Idempotency-Key su ogni ordine e ricarica. Se la tua richiesta va in timeout e riprovi con la stessa chiave, l'API deve restituire il risultato originale invece di creare una seconda eSIM a pagamento.

Come testare: invia lo stesso ordine due volte con la stessa chiave e conferma di ricevere un solo ordine. Poi invia la stessa chiave con un corpo diverso — una buona API la rifiuterà. TripoSIM richiede la chiave per gli ordini in produzione e le ricariche e restituisce 409 IDEMPOTENCY_KEY_REUSED se una chiave viene riutilizzata con una richiesta diversa.

3. Preventivi che bloccano il prezzo

Cosa cercare: un modo per recuperare un prezzo e mantenerlo per un breve periodo, in modo che il tuo cliente paghi esattamente ciò che gli hai mostrato.

Come testare: crea un preventivo, attendi, quindi ordina con esso. I preventivi TripoSIM sono validi per 10 minuti; un preventivo scaduto restituisce 409 QUOTE_EXPIRED, così puoi generare un nuovo preventivo invece di addebitare un prezzo a sorpresa.

4. Un catalogo pulito

Cosa cercare: un endpoint che elenchi ogni piano con prezzo, dati, validità, paesi coperti, 5G, supporto alle ricariche — e per i piani illimitati, il limite giornaliero di velocità massima.

Come testare: estrai il catalogo per un paese e confrontalo con il sito web del fornitore. L'endpoint TripoSIM /catalog restituisce JSON o CSV, include i piani regionali che coprono il paese e aggiunge i campi per l'uso corretto (fup_daily_mb, fup_throttle_kbps) per i piani illimitati. Guarda [come funzionano i limiti giornalieri illimitati](/blog/unlimited-esim-daily-limit-by-country-2026).

5. Consegna istantanea di ordine e QR

Cosa cercare: la risposta all'ordine (o un webhook pochi secondi dopo) dovrebbe includere il codice di attivazione nel formato standard LPA, ad esempio LPA:1$smdp.example.com$ACTIVATION_CODE, in modo da poter mostrare un codice QR o un link di installazione con un tocco.

Come testare: effettua un ordine nel sandbox, genera il QR dalla stringa LPA e scansionalo con la fotocamera di un telefono per verificare che il formato sia valido.

6. Webhook firmati per ogni evento

Cosa cercare: notifiche push per l'intero ciclo di vita della eSIM, firmate in modo che gli attaccanti non possano falsificarle.

TripoSIM invia otto tipi di eventi: order.completed, order.failed, esim.activated, esim.usage_80, esim.suspended, esim.resumed, esim.depleted e esim.expired. Ogni richiesta porta un header X-TripoSIM-Signature — un HMAC-SHA256 del timestamp e del corpo grezzo utilizzando il tuo segreto di firma:

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

Come testare: registra un webhook, attiva un ordine e verifica la firma nel tuo codice. Poi cambia un byte del corpo e assicurati che il tuo controllo lo rifiuti.

7. Un sandbox che simula l'intera vita della eSIM

Cosa cercare: le eSIM reali richiedono giorni per essere attivate e consumare dati. Un buon sandbox ti permette di accelerare i tempi.

Come testare: nel sandbox TripoSIM, usa POST /sandbox/esims/{iccid}/simulate con un'azione di activate, usage, deplete, expire o reset. Ogni passaggio attiva il relativo webhook, così puoi testare la tua email "i tuoi dati stanno per finire" in pochi minuti invece di giorni.

8. Simulazione dei guasti

Cosa cercare: un modo per forzare gli errori appositamente, in modo da sapere che la tua app li gestisce correttamente.

Come testare: invia l'header X-Sandbox-Simulate con modalità come insufficient_balance, price_changed, rate_limit, provider_unavailable o timeout, e verifica che la tua app mostri un messaggio chiaro e riprovi solo quando deve.

9. Ricariche sulla stessa eSIM

Cosa cercare: i clienti che esauriscono i dati dovrebbero essere in grado di aggiungerne altri senza installare una nuova eSIM.

Come testare: chiama POST /esims/{iccid}/topup nel sandbox (con una chiave di idempotenza), quindi controlla il nuovo saldo dati. Controlla anche quali piani supportano le ricariche — il catalogo dovrebbe indicartelo.

10. Dati di utilizzo e stato

Cosa cercare: un endpoint per i dati utilizzati, i dati rimanenti e la scadenza, in modo che il tuo team di supporto e la tua app possano rispondere a "quanti dati mi rimangono?".

Come testare: chiama GET /esims/{iccid}/usage dopo un evento di utilizzo simulato. TripoSIM memorizza l'utilizzo per 5 minuti, quindi usa i webhook (esim.usage_80, esim.depleted) per avvisi in tempo reale.

11. Sospensione e ripristino

Cosa cercare: un modo per mettere in pausa una eSIM — ad esempio quando un pagamento viene contestato o un cliente segnala uno smarrimento del telefono — e ripristinarla in seguito.

Come testare: sospendi una eSIM nel sandbox, conferma che arrivi il webhook esim.suspended, quindi ripristinala e conferma esim.resumed.

12. Limiti di velocità, codici di errore e changelog chiari

Cosa cercare: limiti documentati, codici di errore che ti dicono se riprovare e un changelog pubblico in modo che gli aggiornamenti non ti sorprendano mai.

Come testare: leggi la lista degli errori e mappa ogni codice a "riprova" o "non riprovare" nel tuo codice. TripoSIM consente 120 richieste al minuto per account partner (puoi impostare limiti inferiori per le singole chiavi API), restituisce un header Retry-After sulle risposte 429, contrassegna ogni codice di errore come riproovabile o meno e pubblica un endpoint changelog.

Un semplice piano di lancio

1. Giorno 1: ottieni le chiavi del sandbox, autenticati, estrai il catalogo.
2. Giorno 2: effettua ordini nel sandbox con chiavi di idempotenza e mostra i codici QR.
3. Giorno 3: aggiungi i webhook, esegui i simulatori di ciclo di vita e di guasto.
4. Giorno 4: aggiungi ricariche e utilizzo, quindi testa su un telefono reale con una eSIM live.
5. Giorno 5: vai online.

La maggior parte dei team si connette in meno di una settimana. Leggi la [documentazione API](https://docs.triposim.com) completa o consulta la nostra [guida all'integrazione dell'API eSIM](/blog/esim-reseller-api-how-to-integrate-travel-esim-sales-into-your-platform) passo dopo passo.

Domande frequenti

Cosa dovrebbe includere un'API eSIM per viaggi?

Al minimo: autenticazione tramite token, chiavi di idempotenza, preventivi, un feed del catalogo, codici QR/attivazione istantanei, webhook firmati, un sandbox con simulatori di ciclo di vita e guasti, ricariche, dati di utilizzo, sospensione/ripristino e limiti di velocità e codici di errore documentati.

Perché le chiavi di idempotenza sono importanti per un'API eSIM?

Ogni ordine eSIM costa denaro reale. Se una richiesta va in timeout e il tuo sistema riprova, una chiave di idempotenza assicura che il tentativo di riprova restituisca il primo risultato invece di acquistare una seconda eSIM.

Come posso testare un'API eSIM senza acquistare eSIM?

Usa il sandbox. Un buon sandbox simula ordini, attivazione, utilizzo dati, esaurimento e scadenza — e ti permette di forzare gli errori — senza addebitare il tuo portafoglio.

Quanto tempo richiede l'integrazione di un'API eSIM?

Con un'API ben documentata e un sandbox completo, la maggior parte dei team va online in 3–5 giorni lavorativi.

L'API TripoSIM supporta la consegna white-label?

Sì. Ricevi il codice di attivazione e i dati QR, così puoi consegnare la eSIM all'interno della tua app o delle tue email sotto il tuo marchio. Vedi il [programma API](/api-program).

In sintesi

Il prezzo conta, ma per un'API eSIM la vera differenza si vede dopo il lancio: tentativi di riprova che non causano mai doppi addebiti, webhook di cui puoi fidarti e un sandbox che ti permette di testare tutto in anticipo. Esegui questa checklist su qualsiasi fornitore prima di impegnarti — e [inizia con il nostro sandbox](/api-program) per vedere come si comporta l'API Partner di TripoSIM.