Il plafond

Il plafond è la risorsa consumabile che il tuo account ha a disposizione per creare ordini sull'API Sterna. Ogni ordine consuma una quota del plafond; quando il plafond si esaurisce, non è più possibile creare nuovi ordini fino a quando non viene ricaricato.

Questa pagina spiega come funziona il plafond, come leggerlo nella risposta di un ordine, e — punto importante — quali operazioni sul plafond si fanno via API e quali invece si gestiscono dal pannello Sterna.

Cos'è il plafond

Il plafond rappresenta una quantità prepagata di risorsa associata al tuo account. La risorsa è tipicamente espressa in volume di traffico dati (megabyte), ma il modello è generico e in futuro potrebbero esistere plafond su altre risorse.

Ogni volta che crei un ordine, l'API calcola quanta risorsa serve per evadere quell'ordine, la scala dal plafond, e ti restituisce nella risposta il nuovo saldo. Il calcolo è automatico: non devi tu indicare quanto consumare.

Risorsa — il tipo di credito (per esempio data_mb per megabyte di traffico dati).
Saldo — quanta risorsa è ancora disponibile sul tuo account in un dato momento.
Consumo — la quota di risorsa scalata da un singolo ordine.

Come si consuma il plafond

Il plafond si consuma automaticamente alla creazione di ogni ordine. La risposta di POST /v1/orders contiene un blocco plafond che ti dice esattamente cos'è successo: per ciascuna risorsa coinvolta vedi quanto è stato consumato da questo ordine e qual è il saldo rimanente subito dopo.

Ecco un esempio del solo blocco plafond come compare nella risposta di un ordine (valori a scopo illustrativo):

[
  {
    "resource_type": "data_mb",
    "consumed": 102400,
    "new_balance": 409600
  }
]

In questo esempio l'ordine ha consumato 102.400 MB (≈ 100 GB) di plafond dati, e dopo l'operazione restano 409.600 MB (≈ 400 GB) disponibili sull'account. Il blocco è sempre un array, perché in futuro un singolo ordine potrebbe toccare più tipi di risorsa.

Il blocco `plafond` nella risposta dell'ordine

Ogni elemento dell'array plafond ha tre campi. La tabella seguente li descrive.

Campo	Tipo	Significato
`resource_type`	stringa	Tipo di risorsa consumata. Valore attualmente noto: `data_mb` (megabyte di traffico dati).
`consumed`	intero	Quantità di risorsa scalata da questo ordine, espressa nell'unità del `resource_type` (per `data_mb`, in megabyte).
`new_balance`	intero	Saldo della risorsa rimasto sull'account subito dopo l'ordine, nella stessa unità di `consumed`.

Il blocco plafond riflette lo stato al momento della risposta: è una fotografia, non un valore aggiornato in tempo reale. Per conoscere il saldo corrente in un momento diverso, vedi la sezione «Consultare il saldo» più sotto.

Come si ricarica o si assegna il plafond

La ricarica del plafond non è disponibile via API. Il plafond del tuo account viene caricato dal pannello Sterna, secondo gli accordi commerciali in essere. Non esiste una chiamata API che ti permetta di aggiungere credito al tuo account in autonomia.

Se il tuo account è l'account principale di un gruppo (vedi la pagina «Ordini in una rete»), anche l'assegnazione di plafond ai sotto-account è un'operazione da pannello, non via API. Dal pannello decidi quanta risorsa ciascun sotto-account può consumare; i sotto-account, via API, vedranno il loro plafond ridursi a ogni ordine esattamente come descritto sopra.

Tutte le operazioni di ricarica e di assegnazione di plafond si fanno dal pannello Sterna. L'API si occupa solo del consumo del plafond a ogni ordine.

Consultare il saldo

Il modo certo per conoscere il saldo del plafond via API è leggere il campo new_balance nel blocco plafond della risposta di un ordine: quel valore è il saldo aggiornato subito dopo l'ordine.

[DA VERIFICARE] Esiste un endpoint dedicato (per esempio GET /v1/balance) per consultare il saldo del plafond senza dover creare un ordine? Se sì, lo documentiamo qui. Se no, dichiariamo esplicitamente che il saldo, fuori dal contesto di un ordine, si consulta dal pannello Sterna.

Il plafond si riduce a ogni ordine; la risposta dell'API restituisce il saldo aggiornato.

Cosa succede se il plafond non basta

Se il plafond residuo non è sufficiente a coprire il consumo richiesto da un ordine, la chiamata POST /v1/orders fallisce e l'ordine non viene creato (non viene scalato nulla dal plafond). Il comportamento esatto — codice di stato HTTP e identificatore di errore restituito — è descritto nella pagina «Gestione degli errori».

Cosa non cambia

Gli endpoint restano gli stessi: POST /v1/orders per creare un ordine, GET /v1/catalog per il catalogo. Il plafond non aggiunge nuovi endpoint obbligatori.
L'autenticazione non cambia: continui a usare la chiave del tuo account (stk_test_... in ambiente test, stk_live_... in ambiente live).
Il ciclo di vita dell'ordine è identico: il consumo del plafond avviene alla creazione e non altera gli stati successivi dell'ordine.
L'eSIM consegnata al tuo cliente è la stessa: il plafond riguarda la contabilità del tuo account, non il prodotto finale.