Integra l'eSIM API

Usa l'eSIM API per acquistare pacchetti dati e fornire i dettagli di installazione dalla tua applicazione. Servono uno spazio di lavoro, una chiave API e fondi nel wallet dell'organizzazione per gli acquisti in produzione. Segui l'autenticazione e usa la regione API corrispondente alla tua chiave.

Assegna alla chiave esim:read per consultare offerte e risorse, e esim:write per acquistare o gestire il servizio. Le credenziali di installazione hanno permessi separati: esim_credentials:read per recuperarle e esim_credentials:write per creare o inviare link di installazione. Conserva la chiave API nella tua applicazione server.

1. Scegli un'offerta

Elenca le offerte per la destinazione, poi ottieni l'offerta selezionata. Verifica zone.countries, il volume e la validità in pricing, le condizioni di velocità e l'eventuale servizio telefonico incluso. Per una eSIM esistente, usa Elenca le offerte compatibili: la disponibilità a catalogo non garantisce la compatibilità con la ricarica.

Ottieni i requisiti di identificazione dell'offerta prima di raccogliere le informazioni sull'abbonato. La risposta contiene uno Schema JSON per ogni paese di copertura, che richiede nome, cognome ed email, più eventuali campi aggiuntivi. Abilita la validazione del formato email e data. Raccogli e valida queste informazioni tu: l'eSIM API non riceve né verifica le risposte, e una validazione riuscita non autorizza un acquisto.

Per una nuova eSIM, ottieni le opzioni di checkout. Mostra il prezzo una tantum restituito o il preventivo ricorrente disponibile prima di accettare l'acquisto. I prezzi di checkout sono al netto delle imposte. Il rinnovo ha un prezzo e una cadenza propri; segui pacchetti ricorrenti quando il cliente lo sceglie.

Per l'esempio una tantum qui sotto, installa curl e jq. Imposta BIRD_API_URL sul tuo URL base regionale, BIRD_API_KEY sulla tua chiave e ESIM_OFFER_ID sull'ID dell'offerta selezionata:

curl --fail-with-body --silent --show-error \
  "$BIRD_API_URL/v1/esim/offers/$ESIM_OFFER_ID/checkout" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  > esim-checkout.json

jq '.one_time' esim-checkout.json

Controlla il prezzo e le condizioni dell'offerta prima di proseguire. Il preventivo non riserva la disponibilità.

2. Crea l'acquisto

Crea un ordine con offer_id. Ometti esim_id per un nuovo profilo; includilo per una ricarica. Per un acquisto una tantum, invia offer_revision e expected_price dal preventivo accettato. Questi campi rifiutano condizioni modificate con 409 prima dell'addebito; recupera e rivedi un preventivo aggiornato prima di accettare un prezzo cambiato.

Imposta ESIM_ORDER_KEY su un valore univoco per questo acquisto e salvalo insieme alla richiesta. Questo esempio acquista una nuova eSIM non assegnata e copia il prezzo pubblicato senza modificarne importo o valuta:

jq '{offer_id, offer_revision: .one_time.offer_revision, expected_price: .one_time.price}' \
  esim-checkout.json > esim-order.json

curl --fail-with-body --silent --show-error \
  "$BIRD_API_URL/v1/esim/orders" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $ESIM_ORDER_KEY" \
  --data-binary @esim-order.json

Per assegnare un nuovo profilo al completamento della consegna, includi un subscriber_id dello spazio di lavoro; segui la configurazione dell'abbonato. Una ricarica mantiene l'assegnazione esistente, quindi ometti subscriber_id quando invii esim_id. Invia i dettagli di installazione separatamente dopo la consegna.

Salva l'ID ordine restituito. Ispeziona status anche dopo HTTP 201, che può contenere un ordine completato o fallito. HTTP 202 indica che l'elaborazione è ancora in corso. Ottieni l'ordine finché non è completed o failed. Un ordine completato identifica esim_id e package_id; l'installazione sul dispositivo resta un passaggio separato.

3. Fornisci i dettagli di installazione

Dopo l'acquisto, leggi le credenziali di installazione, crea un link di installazione ospitato oppure invia un link via email o SMS. Tieni i dettagli di attivazione e i link di installazione fuori da analytics e log pubblici.

Per un link inviato, salva l'ID di consegna e controlla la cronologia di consegna. Una risposta 202 conferma l'accettazione per l'invio; delivered conferma la consegna del messaggio, mentre l'installazione sul dispositivo richiede un controllo separato. Segui la guida all'installazione per i metodi supportati, la scadenza del link e il recupero.

4. Recuperare un acquisto interrotto

Se la risposta di creazione è andata persa o ha restituito 503, ripeti la richiesta salvata con il suo Idempotency-Key originale; vedi richieste idempotenti. Se hai l'ID dell'ordine, leggi prima quell'ordine. Creare un altro acquisto mentre l'esito è incerto può causare un ulteriore addebito.

Per un ordine in charging, controlla funding e il saldo del tuo wallet. funding.required_amount è il saldo totale necessario, tasse incluse; confrontalo con i fondi disponibili prima di aggiungere denaro. Gli ordini una tantum riprovano il finanziamento automaticamente. Dopo che un acquisto ricorrente iniziale è rifiutato per fondi insufficienti, aggiungi fondi e riprova esplicitamente la stessa richiesta di creazione con la sua chiave originale.

Controlla lo stato attuale dell'ordine anche dopo funding.lapses_at: quel timestamp non garantisce la cancellazione. Un ordine può comunque completarsi se riceve fondi prima che un ulteriore tentativo per fondi insufficienti lo faccia fallire.

Per interrompere un acquisto non finanziato e indesiderato, cancella l'ordine. Una cancellazione non finanziata riuscita restituisce status: failed e failure_code: canceled. Un ordine una tantum già finanziato restituisce 409 e prosegue. Per un acquisto ricorrente iniziale, il pagamento recuperato durante la cancellazione può lasciare l'acquisto pagato in corso mentre il rinnovo futuro si interrompe. Controlla l'ordine restituito e la sottoscrizione prima di comunicare la cancellazione o un rimborso.

Per un acquisto fallito, controlla failure_code e failure_reason. Qualsiasi addebito viene accreditato automaticamente; refund_transaction_id identifica un credito emesso. Conserva l'ID dell'ordine per il supporto se il pagamento, la consegna o il credito rimane irrisolto.

5. Mostrare saldi e stato del servizio

Ottieni l'eSIM per stato, stato di installazione, pacchetti e available_actions. Visualizza la quota, il consumo e la data e ora della misurazione del pacchetto usando la guida all'utilizzo. Un consumo sconosciuto deve restare sconosciuto nella tua applicazione.

Ricontrolla la disponibilità dell'azione quando il cliente agisce; l'operazione verifica nuovamente permessi e stato. Usa la guida alle operazioni per indagare acquisti incompleti, problemi di installazione o errori di connettività.

Prossimi passi

• Scegli un pacchetto viaggio.
• Prepara l'installazione sul dispositivo.
• Gestisci i pacchetti ricorrenti.