Creare un ordine

Creare un ordine è l'operazione con cui acquisti un prodotto del catalogo. È il cuore dell'integrazione: da qui parte tutto il processo che porta alla consegna dell'eSIM al tuo cliente.

Prima di iniziare

Per creare un ordine ti servono due cose:

• l'id del prodotto che vuoi acquistare, che trovi nel catalogo (vedi la sezione precedente);
• una API key con il permesso write. Una chiave con il solo permesso read non può creare ordini.

L'endpoint

Per creare un ordine si invia una richiesta POST a questo endpoint:

POST /v1/orders

Il corpo della richiesta è un oggetto JSON con due campi: product_id (l'identificativo del prodotto) e quantity (la quantità da ordinare).

Esempio di richiesta

curl -X POST https://api.sterna.mobi/v1/orders \
  -H "Authorization: Bearer stk_test_51H8d..." \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "e9e3cce1-...",
    "quantity": 1
  }'

Esempio di risposta

L'API risponde con i dati dell'ordine appena creato:

{
  "order": {
    "id": "...",
    "order_number": "ORD-2026-000012",
    "status": "processing",
    "environment": "test",
    "product_name": "STERNA Europe Sud",
    "quantity": 1,
    "unit_price_eur": 14.00,
    "total_price_eur": 14.00,
    "created_at": "2026-05-23T10:00:00Z"
  },
  "plafond": [
    {
      "resource_type": "data_mb",
      "consumed": 102400,
      "new_balance": 409600
    }
  ],
  "fulfillment": {
    "status": "processing",
    "provider_order_id": "...",
    "error": null
  }
}

Come leggere la risposta

La risposta è composta da tre parti:

• `order` — I dati dell'ordine creato. Qui trovi il suo id e il suo order_number, che ti serviranno per ritrovare l'ordine in seguito, lo status (lo stato in cui si trova), e i due campi prezzo: unit_price_eur (prezzo unitario applicato) e total_price_eur (totale dell'ordine).
• `plafond` — Il movimento di plafond generato dall'ordine: quanto credito è stato consumato (consumed) e quanto te ne resta (new_balance).
• `fulfillment` — L'esito dell'avvio dell'evasione. Indica che Sterna ha iniziato a preparare l'eSIM presso l'operatore.

Esempio pratico: ordine con prezzo di gruppo

Immagina questa situazione: Account A appartiene a un gruppo gestito da Account B. Nel catalogo, il prodotto «Pacchetto eSIM 10 GB» ha prezzo di riferimento 6,50 €. Account B ha però stabilito per Account A un prezzo di 7,77 € su questo prodotto.

Quando Account A crea un ordine per una unità di questo prodotto, nella risposta dell'API il blocco order contiene questi valori:

{
  "order": {
    "product_name": "Pacchetto eSIM 10 GB",
    "quantity": 1,
    "unit_price_eur": 7.77,
    "total_price_eur": 7.77
  }
}

Il prezzo applicato all'ordine di Account A è 7,77 €, non i 6,50 € del catalogo: è il prezzo che Account B ha impostato per Account A.

Un punto importante: ordine ed eSIM sono due momenti distinti

La creazione dell'ordine e la consegna dell'eSIM non avvengono nello stesso istante. Quando crei l'ordine, questo viene registrato subito e si trova tipicamente in stato processing. L'eSIM, invece, viene preparato e consegnato poco dopo, in modo asincrono — di norma entro pochi secondi.