Sviluppatori

Quattro endpoint, due webhook, nessuna sorpresa.

Tutto quello che fa il negozio lo può fare il tuo prodotto. L'intera superficie sta in una pagina.

REST su HTTPS all'indirizzo api.orbislo.com, autenticazione bearer, JSON in entrata e JSON in uscita. Elenchi il catalogo, crei un ordine, interroghi il job di provisioning, leggi il consumo. Due webhook ti dicono quando una eSIM si attiva e quando sta finendo. Le credenziali della sandbox arrivano lo stesso giorno lavorativo. L'accesso in produzione oggi si ottiene su richiesta, e qui sotto spieghiamo perché invece di far passare il modulo per un limite di traffico.

Perché esiste questa API

La connettività andrebbe attivata nel momento in cui il viaggiatore prenota, dentro il tuo prodotto. Non dovrebbe essere una scoperta fatta in aeroporto.

Una piattaforma di prenotazione può agganciare i dati a un itinerario. Un produttore di dispositivi può attivare un piano durante la configurazione iniziale. Uno strumento per team può consegnare a un nuovo assunto i suoi giga insieme al portatile.

Tutti e tre i casi sono quattro chiamate e un webhook. Non c'è nessun portale partner in cui entrare e nessun CSV da caricare.

Cosa succede tra la tua POST e un viaggiatore che ha campo.

Autenticazione

Manda la tua chiave come token bearer su ogni richiesta. Le chiavi hanno prefisso sk_test per la sandbox e sk_live per la produzione.

Una chiave incollata nell'ambiente sbagliato fallisce con un 401 invece di spendere soldi in silenzio. Le chiavi hanno un ambito, quindi una chiave di sola lettura non può creare un ordine e una chiave emessa per un account di team non ne vede un altro.

Ruotale dalla console quando vuoi. La chiave vecchia continua a funzionare per 24 ore, quindi non sei mai costretto a un cambio in blocco.

curl https://api.orbislo.com/v1/catalog?country=jp \
  -H "Authorization: Bearer sk_live_9f2c..." \
  -H "Orbislo-Version: 2026-08-01"

Sull'header di versione

L'header di versione è opzionale e fissa la forma della risposta a una release datata. Senza, ricevi la versione con cui è nata la tua chiave, che non cambia mai sotto i tuoi piedi.

Aggiungiamo campi senza preavviso. Non togliamo mai un campo e non ne cambiamo mai il tipo dentro una versione.

endpoint in tutta l'API, più 2 eventi webhook

90 s

tempo mediano da un ordine andato a buon fine a un profilo attivo

24 h

finestra in cui una chiave di idempotenza ripetuta restituisce la risposta originale

Gli endpoint

Metodo	Percorso	Cosa fa	Limite di traffico
GET	/v1/catalog	Ogni piano che vendiamo, con prezzo, giga, validità e paesi coperti.	600 al minuto
POST	/v1/orders	Compra un piano e restituisce un ordine con un job di provisioning agganciato.	60 al minuto
GET	/v1/provisioning/:id	Lo stato di un job di provisioning, da queued fino ad activated o failed.	600 al minuto
GET	/v1/usage/:esim_id	Byte consumati, byte rimasti e l'operatore a cui una eSIM è agganciata.	300 al minuto

I limiti valgono per chiave in una finestra scorrevole. Ogni risposta porta il residuo e l'ora di azzeramento, e un 429 porta un ritardo di ritentativo in secondi. Se il tuo caso d'uso ha davvero bisogno di un secchio più grande, chiedi, perché allargarlo è un cambio di configurazione e non una trattativa.

Catalogo

Il catalogo è la fonte di verità su cosa esiste e quanto costa. Copre le 145 destinazioni attive oggi.

Filtra per paese, per regione o per famiglia di piani. I prezzi tornano in unità minori, così la virgola mobile non arriva mai al tuo codice di fatturazione.

GET /v1/catalog?country=jp

{
  "object": "list",
  "data": [
    {
      "id": "plan_jp_5gb",
      "name": "Japan 5 GB",
      "countries": ["jp"],
      "data_mb": 5120,
      "price": { "amount": 1150, "currency": "usd" },
      "expires": false,
      "throttle_mbps": null,
      "tethering": true,
      "carriers": ["NTT Docomo", "KDDI", "SoftBank"]
    }
  ],
  "has_more": false
}

Due campi da leggere due volte

Il campo expires è false su ogni piano a consumo che vendiamo, perché i nostri giga non scadono. Se stai costruendo un confronto prezzi, quel campo cambia i conti più del prezzo stesso.

Il campo throttle_mbps è null sui piani a consumo e 1 sui pass giornalieri illimitati, dove la piena velocità arriva a 2 GB al giorno e poi scende a 1 Mbps.

Mettiamo il numero della riduzione nell'API per lo stesso motivo per cui lo stampiamo sul pulsante di acquisto. Un numero che il viaggiatore scopre dopo è un ticket di assistenza.

Ordini

Un solo POST compra un piano e avvia il provisioning. L'header Idempotency-Key è obbligatorio, non un consiglio.

L'esito peggiore in questa API è un timeout che ti lascia nel dubbio se al viaggiatore sia stato addebitato qualcosa. Una chiave obbligatoria elimina del tutto quello stato.

POST /v1/orders
Idempotency-Key: 4f1d0f6e-1c3a-4a2b-9d77-1b6a0e7c9f21
Content-Type: application/json

{
  "plan_id": "plan_jp_5gb",
  "traveller_ref": "user_88213",
  "imei": "356938035643809",
  "activate": "on_first_use"
}

201 Created

{
  "id": "ord_7Kd2mQ",
  "status": "provisioning",
  "esim_id": "esim_2xB9Ln",
  "provisioning_id": "prv_5Ttq81",
  "amount": { "amount": 1150, "currency": "usd" },
  "activation": {
    "type": "universal_link",
    "url": "https://orbislo.com/i/2xB9Ln",
    "lpa": "LPA:1$rsp.orbislo.com$K4-9TT-2XB9LN"
  }
}

Controllo del dispositivo e attivazione differita

Il campo imei è opzionale ma fortemente consigliato. Mandalo e controlliamo la compatibilità eSIM e il blocco operatore prima di prendere i soldi.

Un telefono che non può ospitare un profilo riceve un 422 con device_not_eligible, invece di un piano venduto e di un viaggiatore arrabbiato.

Impostare activate su on_first_use fa partire qualsiasi finestra di validità quando il viaggiatore atterra, non quando il tuo server ci ha chiamati.

Stato del provisioning

Il provisioning è asincrono, perché dall'altra parte c'è una piattaforma di operatore. Interroga questo endpoint, oppure prendi il webhook e lascia perdere il polling.

Il tempo mediano da queued ad activated sta sotto i 90 secondi. Tutto quello che resta in queued dopo 10 minuti è un fallimento, e si rimborsa da solo.

GET /v1/provisioning/prv_5Ttq81

{
  "id": "prv_5Ttq81",
  "status": "activated",
  "states": [
    { "state": "queued",       "at": "2026-08-24T09:14:02Z" },
    { "state": "provisioning", "at": "2026-08-24T09:14:04Z" },
    { "state": "installed",    "at": "2026-08-24T09:14:41Z" },
    { "state": "activated",    "at": "2026-08-24T09:15:07Z" }
  ],
  "carrier": "KDDI",
  "failure_reason": null
}

Webhook

Due eventi, e tutti e due cambiano quello che va detto al viaggiatore. Puntali su qualsiasi endpoint HTTPS, impostato separatamente per ambiente.

Eventi webhook

Evento	Scatta quando	Cosa farne
esim.activated	Il profilo si aggancia a una rete per la prima volta.	Dì al viaggiatore che è online. È il momento in cui l'acquisto diventa reale per lui.
esim.depleted	Il piano supera una soglia di consumo, all'80 per cento e di nuovo al 100 per cento.	Proponi una ricarica prima che resti a piedi, non dopo.

POST https://your-app.example/hooks/orbislo
Orbislo-Signature: t=1756032907,v1=6c1b...
Content-Type: application/json

{
  "id": "evt_9pQ4rz",
  "type": "esim.depleted",
  "created": "2026-08-24T11:41:33Z",
  "data": {
    "esim_id": "esim_2xB9Ln",
    "threshold": 80,
    "used_mb": 4096,
    "remaining_mb": 1024,
    "country": "jp"
  }
}

Verificare una consegna

Calcola HMAC SHA-256 sul timestamp, un punto e il corpo grezzo della richiesta, usando il secret del tuo endpoint. Confronta a tempo costante.

Rifiuta qualsiasi cosa con un timestamp più vecchio di 5 minuti, così fermi un replay. Le consegne sono almeno una volta e vengono ritentate 8 volte nell'arco di 24 ore, quindi indicizza il tuo handler sull'id dell'evento.

Codici di errore

HTTP	Codice	Cosa significa	Cosa fare
400	invalid_request	Manca un campo o ha il tipo sbagliato. Il corpo dice quale campo.	Correggi la richiesta. Ritentare non serve.
401	invalid_token	Il token bearer è sbagliato, revocato, o viene dall'altro ambiente.	Controlla di non stare mandando una chiave sandbox all'host di produzione.
402	insufficient_balance	Il saldo del tuo account non copre l'ordine.	Ricarica, poi ritenta con la stessa chiave di idempotenza.
404	not_found	In questo ambiente non esiste nessun oggetto con quell'id.	Gli id di sandbox e quelli di produzione non sono intercambiabili.
409	idempotency_conflict	La stessa chiave di idempotenza è stata riusata con un corpo diverso.	Usa una chiave nuova, oppure rimanda il corpo originale byte per byte.
422	device_not_eligible	Il dispositivo non supporta la eSIM, oppure è bloccato dall'operatore.	Fai il controllo del dispositivo prima di prendere i soldi.
429	rate_limited	Sei andato oltre il secchio di quell'endpoint.	Rallenta usando il ritardo di ritentativo nell'header. Non insistere in ciclo.
500	internal_error	Colpa nostra. È già nei nostri allarmi.	Ritenta con la stessa chiave di idempotenza dopo 2 secondi.
503	provider_unavailable	Una piattaforma di operatore a monte è giù.	Ritenta fino a 10 minuti. Dove esiste un secondo operatore passiamo in automatico.

Ogni corpo di errore porta un codice, un messaggio leggibile da una persona e un id di richiesta. Cita l'id di richiesta all'assistenza e salti le prime quattro domande.

Oggi l'accesso in produzione si ottiene su richiesta, ed è un limite vero.Non puoi iscriverti alle 2 di notte ed essere in provisioning alle 3, il che è onestamente peggio di una API in autonomia. Non lo chiameremo un percorso di ingresso curato. Una chiave di produzione muove denaro e crea un profilo di operatore, e preferiamo leggere un paragrafo su quello che stai costruendo piuttosto che rimediare a una chiave finita in giro. Le credenziali della sandbox arrivano lo stesso giorno lavorativo, quindi niente ti impedisce di scrivere l'integrazione mentre leggiamo.

Sandbox contro produzione

Stesso host, stessi percorsi, stesse forme di risposta. Una chiave con prefisso sk_test non tocca mai denaro e non crea mai un profilo di operatore.

I job di provisioning attraversano tutta la macchina a stati in circa 4 secondi, così i tuoi test non dormono 90 secondi ciascuno.

Ordina il piano con id plan_test_fail per ottenere un job fallito con il suo motivo. Ordina plan_test_slow per averne uno che resta in provisioning per 11 minuti, così metti alla prova il tuo percorso di timeout.

Anche in sandbox le consegne webhook partono, verso una URL che imposti per ambiente.

Se preferisci non costruire niente

Il programma di affiliazione paga sugli ordini segnalati senza nessuna integrazione, ed è la risposta giusta per la maggior parte dei siti di contenuti.

L'endpoint MCP espone il nostro insieme di dati sulla copertura e l'indice prezzi a un assistente di intelligenza artificiale con una riga di configurazione e zero codice.

I piani che venderesti, i dati di velocità misurata dietro al catalogo e l'elenco completo dei paesi sono tutti pubblicati apertamente su questo sito.

Le domande che fanno gli sviluppatori

Posso avere una chiave API oggi?

Non in autonomia. Adesso l'accesso si ottiene su richiesta, ed è una scelta voluta, non una coda che ci siamo dimenticati di aprire. Ogni chiave di produzione può muovere soldi veri e creare un profilo vero su una piattaforma di operatore vera, e una chiave rubata costa a un viaggiatore la sua connessione. Per questo leggiamo le richieste. La sandbox è un altro discorso: chiedi e ricevi le credenziali lo stesso giorno lavorativo, senza contratto e senza impegno.

Quanto tempo serve per l'approvazione?

Due giorni lavorativi per la prima risposta e di solito meno di una settimana in tutto. Vogliamo sapere cosa stai costruendo, più o meno quante attivazioni al mese ti aspetti e quali paesi. Se pensiamo che l'API non sia lo strumento giusto per quello che ci hai descritto, te lo diciamo e ti indirizziamo al programma di affiliazione, che paga senza nessun lavoro di sviluppo.

Che differenza c'è tra sandbox e produzione?

La sandbox usa lo stesso host con una chiave dal prefisso sk_test. Restituisce il catalogo vero, accetta ordini e porta un job di provisioning attraverso queued, provisioning e activated su una linea temporale compressa di circa 4 secondi. Non si muove denaro e non nasce nessun profilo di operatore. Puoi forzare qualsiasi stato di errore ordinando il piano con id plan_test_fail. Le chiavi di produzione hanno prefisso sk_live e lì è tutto reale.

Mi servono le chiavi di idempotenza?

Sulla creazione dell'ordine sì, e senza chiave l'endpoint rifiuta la richiesta. Un timeout di rete su un ordine è l'ambiguità più cara di questa API, perché ritentare alla cieca compra il piano due volte. Manda un UUID nell'header Idempotency-Key. Conserviamo la chiave accanto alla risposta per 24 ore, quindi un ritentativo dentro quella finestra restituisce il risultato originale invece di creare un secondo ordine.

Quali sono i limiti di traffico?

600 richieste al minuto sugli endpoint di lettura, 300 al minuto sul consumo e 60 al minuto sulla creazione degli ordini, per chiave, in una finestra scorrevole. Ogni risposta porta il residuo e l'ora di azzeramento. Un 429 porta un ritardo di ritentativo in secondi. Se il tuo caso d'uso ha davvero bisogno di più, chiedi, perché allargare un secchio è un cambio di configurazione e non una trattativa.

Quanto sono affidabili i webhook?

Ritentiamo una risposta diversa da 2xx 8 volte nell'arco di 24 ore con attesa esponenziale, partendo da 10 secondi. Ogni consegna è firmata con HMAC SHA-256 sul corpo grezzo usando il secret del tuo endpoint, con un timestamp che dovresti controllare contro una finestra di 5 minuti per fermare i replay. Le consegne sono almeno una volta, quindi rendi il tuo handler idempotente sull'id dell'evento.

Esiste un SDK?

C'è un client TypeScript e un client Python, tutti e due sottili involucri sugli stessi quattro endpoint. Nessuno dei due nasconde niente. Il formato sul filo è abbastanza stabile da rendere curl un client di produzione ragionevole. Preferiamo documentare bene il formato sul filo che mantenere male undici SDK.

Cosa succede quando il provisioning fallisce?

Il job passa a failed con un motivo, facciamo partire il webhook di attivazione con quello stato, e l'ordine si rimborsa da solo entro 60 secondi senza che nessuno lo chieda. Per questo caso non devi costruire nessun percorso di rimborso. Devi però gestire lo stato failed, perché il tuo viaggiatore resta senza giga e va avvisato subito.

Parti dalla sandbox, oppure salta del tutto il codice

Le credenziali della sandbox arrivano lo stesso giorno lavorativo. Se preferisci non scrivere un'integrazione, né il programma di affiliazione né l'endpoint MCP richiedono di costruire qualcosa.

Vai al negozio Vedi tutte le tariffe Guarda le velocità misurate Sfoglia le destinazioni