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,
    "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, e lo status, cioè lo stato in cui si trova.
• `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.

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.