Ciclo di vita dell'ordine

Quando crei un ordine, Sterna avvia automaticamente l'evasione presso l'operatore. L'eSIM non è disponibile immediatamente: viene preparato in modo asincrono, normalmente entro pochi secondi. Questa sezione spiega gli stati che un ordine attraversa e come recuperare l'eSIM quando è pronto.

Gli stati di un ordine

Un ordine può trovarsi in uno di questi stati:

• `pending` — Ordine appena creato, evasione non ancora avviata.
• `processing` — Evasione avviata. L'eSIM è in preparazione presso l'operatore.
• `completed` — Evasione completata. L'eSIM è pronto e disponibile.
• `failed` — L'evasione non è andata a buon fine. Il campo error_message ne indica il motivo.

Subito dopo la creazione, un ordine si trova tipicamente in stato processing. Diventa completed quando l'eSIM è stato allocato.

Recuperare un ordine e il suo eSIM

Per conoscere lo stato di un ordine e recuperarne i dati, interroghi il dettaglio dell'ordine usando il suo id:

GET /v1/orders/{id_ordine}

curl https://api.sterna.mobi/v1/orders/{id_ordine} \
  -H "Authorization: Bearer stk_test_51H8d..."

L'eSIM nella risposta

Quando l'ordine è in stato completed, la risposta include il campo esim con i dati del profilo:

{
  "order": {
    "id": "...",
    "order_number": "ORD-2026-000012",
    "status": "completed",
    "completed_at": "2026-05-23T10:00:30Z",
    "esim": [
      {
        "iccid": "8943108170000775671",
        "activation_code": "LPA:1$rsp.example.com$ABC123",
        "qr_code_url": "https://.../qrcode.png",
        "smdp_status": "RELEASED",
        "esim_status": "GOT_RESOURCE",
        "expired_time": "2026-06-22T10:00:00Z"
      }
    ]
  }
}

I campi principali dell'eSIM sono:

• `iccid` — L'identificativo univoco dell'eSIM.
• `activation_code` — Il codice di attivazione (formato LPA:...), da usare per installare il profilo manualmente.
• `qr_code_url` — L'indirizzo dell'immagine del QR code. Il tuo cliente finale può inquadrarlo per installare l'eSIM sul proprio dispositivo.
• `expired_time` — La data di scadenza del profilo.

Come sapere quando l'ordine è pronto

Poiché l'eSIM viene allocato in modo asincrono, dopo aver creato un ordine devi interrogarne il dettaglio per sapere quando è pronto. Il procedimento è semplice:

1. 1
   Crea l'ordine

   Come visto nella sezione precedente. Appena creato, l'ordine è tipicamente in stato processing.
2. 2
   Attendi qualche secondo

   L'eSIM viene preparato presso l'operatore. Di norma bastano pochi secondi.
3. 3
   Interroga il dettaglio dell'ordine

   Chiama GET /v1/orders/{id}. Se lo stato è ancora processing, attendi ancora qualche secondo e riprova.
4. 4
   Recupera l'eSIM

   Quando lo stato è completed, la risposta contiene il campo esim con tutti i dati del profilo.

Lista degli ordini

Per ottenere l'elenco dei tuoi ordini più recenti puoi usare questo endpoint:

GET /v1/orders

La lista restituisce i dati essenziali di ciascun ordine. Per ottenere anche i dati dell'eSIM, interroga il dettaglio del singolo ordine come mostrato sopra.