Introduzione

Benvenuto nella documentazione dell'API Sterna. Questa guida ti accompagna passo passo nell'integrazione dei servizi di connettività Sterna nella tua piattaforma: dall'autenticazione alla creazione del primo ordine, fino al recupero dell'eSIM consegnato al tuo cliente.

L'API è progettata per essere semplice da integrare. Non devi gestire operatori, attivazioni o infrastruttura di rete: tu effettui le chiamate, Sterna si occupa di tutto il resto. Se segui le sezioni di questa guida nell'ordine in cui sono presentate, al termine avrai un'integrazione completa e funzionante.

Cosa puoi fare con l'API Sterna

L'API Sterna ti permette di rivendere servizi di connettività — a partire dai pacchetti dati eSIM — direttamente dalla tua piattaforma, con il tuo brand e i tuoi prezzi.

Il modello è semplice: tu integri l'API una volta sola, poi ogni volta che un tuo cliente ha bisogno di connettività la tua piattaforma crea un ordine tramite l'API. Da quel momento Sterna gestisce l'intero processo: l'approvvigionamento del servizio presso l'operatore, l'attivazione e la consegna del profilo eSIM, completo di codice di attivazione e QR code pronto all'uso. Il tuo cliente riceve un servizio funzionante; tu non hai gestito nulla a livello tecnico o di rete.

Concetti di base

Prima di iniziare, è utile conoscere quattro concetti che ricorrono in tutta la documentazione. Li ritroverai in ogni sezione, quindi vale la pena familiarizzare fin da subito.

• Prodotto — Un servizio acquistabile dal catalogo Sterna: per esempio un pacchetto dati eSIM per una certa area geografica, con una soglia di traffico e una validità. Ogni prodotto ha un identificativo univoco che userai per ordinarlo. Il catalogo che vedi è già personalizzato sul tuo account, con i prezzi applicati a te.
• Ordine — La richiesta di acquisto di un prodotto. Quando crei un ordine, Sterna avvia automaticamente l'evasione presso l'operatore. L'ordine non è istantaneo: attraversa una serie di stati, dalla creazione fino al completamento.
• Plafond — Il credito di risorse a tua disposizione, concordato con Sterna. Ogni ordine che crei consuma una parte del plafond associato al tuo account. Ogni movimento viene registrato, così puoi sempre sapere quanto credito ti resta.
• eSIM — Il profilo digitale consegnato al termine dell'evasione di un ordine. Include tutti i dati necessari all'attivazione: l'identificativo ICCID, il codice di attivazione e l'indirizzo del QR code che il tuo cliente finale può inquadrare per installare il servizio sul proprio dispositivo.

Il flusso di integrazione: dal primo accesso al primo ordine

L'integrazione completa segue quattro passi. Ogni passo corrisponde a una sezione di questa guida, e tutti insieme formano il percorso che ti porta dal primo accesso fino all'eSIM consegnato.

1. 1
   Autenticati

   Ogni chiamata all'API usa la tua API key. Il primo passo è verificare che l'autenticazione funzioni, con una semplice chiamata di identità.
2. 2
   Consulta il catalogo

   Recuperi l'elenco dei prodotti che puoi vendere, ciascuno con il suo identificativo e il prezzo applicato al tuo account.
3. 3
   Crea un ordine

   Scegli un prodotto dal catalogo e crei un ordine. Sterna avvia subito l'evasione presso l'operatore.
4. 4
   Recupera l'eSIM

   Quando l'ordine è completato, ne recuperi i dati dell'eSIM: ICCID, codice di attivazione e QR code, pronti per il tuo cliente.

Cosa ti serve per iniziare

Per seguire questa guida e integrare l'API ti servono soltanto due cose:

• Una API key Sterna — È la credenziale che identifica il tuo account e autentica ogni chiamata. Ti viene fornita da Sterna. Se non ne hai ancora una, contatta il tuo referente Sterna.
• La capacità di effettuare chiamate HTTP — L'API è una normale API REST: qualsiasi linguaggio di programmazione moderno è in grado di usarla. In questa guida troverai esempi pronti da copiare.

Puoi sviluppare e provare l'intera integrazione senza alcun costo: Sterna mette a disposizione un ambiente di test in cui gli ordini vengono simulati e non viene addebitato nulla. Passerai all'ambiente reale solo quando l'integrazione è pronta. Trovi tutti i dettagli nella sezione "Ambiente test e live".

Come funziona l'API

Tutte le chiamate usano il metodo HTTP appropriato — GET per leggere dati, POST per creare un ordine — e scambiano dati in formato JSON, sia in richiesta sia in risposta.