Controllare il consumo e aggiungere una ricarica
Usa questa guida per aggiungere dati a una eSIM esistente. Devi avere il permesso di leggere la eSIM e acquistare un pacchetto, oltre a fondi sufficienti nel wallet. La disponibilità delle ricariche dipende dal profilo, dai pacchetti esistenti e dall'offerta selezionata.
1. Controllare i pacchetti attivi
Apri il profilo da eSIMs ed esamina Data packages. Con API, elenca i pacchetti della eSIM e controlla stato, scadenza e saldo.
balance.total_bytes è il volume acquistato. Se used_bytes, remaining_bytes o used_percent è null, non è disponibile alcuna misurazione. Tratta quei valori come sconosciuti nella tua applicazione.
Leggi il campo balance_reporting dell'eSIM per decidere cosa mostrare. Se è unavailable, mostra il volume acquistato senza presentarlo come dato residuo misurato. Se è available, il consumo può comunque risultare sconosciuto finché non arriva un report. Lo storico giornaliero dei consumi è separato e al momento non è disponibile.
Usa balance.as_of per l'ora dell'ultimo aggiornamento del saldo; prima che il consumo venga segnalato, può corrispondere all'ora di consegna del pacchetto. balance.observed_at è l'ora della misurazione di rete, quando disponibile. Mostra il timestamp insieme ai dati di consumo misurati, così il cliente può riconoscere un report in ritardo.
2. Elencare le offerte compatibili
Seleziona Top up sulla eSIM oppure chiama List compatible offers per quel profilo. Usa un'offerta restituita anziché sceglierne una dal catalogo generale. La copertura nello stesso paese non garantisce la compatibilità.
Se un top-up non è disponibile, leggi available_actions sull'eSIM per conoscere il motivo. Un ordine non completato o il limite di pacchetti possono impedire un altro acquisto. Risolvi l'ordine esistente prima di riprovare. Aggiorna le offerte compatibili prima di inviare la richiesta: un'offerta può diventare non disponibile tra la selezione e l'acquisto.
Un'eSIM in expired è inattiva e può tornare a active dopo il completamento di un top-up compatibile. Verifica l'azione disponibile e le offerte compatibili prima di decidere che il profilo installato debba essere sostituito.
3. Verificare le condizioni effettive
Mostra il volume, la copertura, il prezzo pubblicato con la valuta e la validità dell'offerta selezionata. Confronta la validità del nuovo pacchetto con il limite di servizio active_until dell'eSIM, quando presente. Se quel limite ridurrebbe la validità acquistata, l'ordine restituisce 409 con la validità effettiva. Mostra il periodo più breve e ottieni l'accettazione prima di impostare acknowledge_shortened_validity: true.
Una ricarica crea un nuovo pacchetto. Non modifica il saldo di un pacchetto esistente né ne estende la scadenza. Verifica l'attivazione e la scadenza del nuovo pacchetto dopo la consegna.
4. Approvare e seguire l'ordine
Conferma l'acquisto nella dashboard. Con la API, crea un ordine usando l'esim_id esistente, l'offer_id selezionato, il revision dell'offerta come offer_revision e il suo pricing.price come expected_price. Ometti subscriber_id; un top-up mantiene l'assegnazione esistente. Salva l'ID dell'ordine e un Idempotency-Key per i tentativi successivi.
Se il prezzo accettato o la revisione sono cambiati, recupera l'offerta corrente e conferma le nuove condizioni prima di inviare un altro acquisto. Copia l'importo e la valuta restituiti senza conversione né arrotondamento.
Segui l'ordine in Orders oppure recupera l'ordine tramite API. Controlla status dopo entrambe le risposte 201 e 202. Se la risposta viene persa, ripeti la stessa richiesta con la stessa chiave; non creare un acquisto sostitutivo finché l'esito è incerto.
5. Controllare il pacchetto risultante
Quando l'ordine è completed, usa il suo package_id per ottenere il nuovo pacchetto. Verifica che l'eSIM di destinazione, la copertura e il volume corrispondano all'acquisto. Il top-up usa il profilo installato; non è necessario installare una nuova eSIM. Un pacchetto in attesa del primo utilizzo può non avere ancora un timestamp di attivazione o scadenza.
Risoluzione dei problemi
Se l'ordine è completato ma il saldo resta sconosciuto, confronta lo stato del pacchetto e i timestamp dei report. La segnalazione può essere in ritardo rispetto al consumo del dispositivo; effettuare un nuovo ordine non risolve quel ritardo. Se un acquisto fallisce, esamina i dettagli dell'errore e l'eventuale riferimento di credito prima di riprovare.
Passaggi successivi
Risorse correlate
Continua con la documentazione, le guide e gli esempi per questo argomento.