Ordini in una rete

Questa pagina spiega come si comporta l'API quando il tuo account fa parte di un gruppo amministrato da un altro account. Cambia poco rispetto a un'integrazione standard: gli endpoint, l'autenticazione e il ciclo di vita dell'ordine restano gli stessi. L'unica cosa che cambia, e va capita bene, è come viene determinato il prezzo dell'ordine.

Cosa significa far parte di un gruppo

Per «gruppo» si intende un insieme di account amministrato da un account principale. L'account principale gestisce dal pannello quali account fanno parte del gruppo, e che condizioni economiche applicare a ciascuno.

Per «livello» si intende il prezzo che l'account principale ha impostato per il tuo account su uno specifico prodotto. È il prezzo che sostituisce quello del catalogo quando il tuo account crea un ordine.

Cosa cambia per la tua integrazione

Se il tuo account fa parte di un gruppo, la tua integrazione cambia in un solo punto: il prezzo applicato all'ordine. Tutto il resto rimane identico a quanto descritto nelle pagine precedenti.

• Autenticazione — identica. Usi la chiave del tuo account (stk_test_... in ambiente test, stk_live_... in ambiente live), generata dal pannello dall'account principale e consegnata a te.
• Catalogo — identico. GET /v1/catalog ti restituisce gli stessi prodotti, con price_eur che resta il prezzo di riferimento del catalogo.
• Ordine — POST /v1/orders si chiama allo stesso modo, ma nella risposta unit_price_eur riflette il prezzo del tuo livello, non price_eur del catalogo.

Come viene determinato il prezzo

Quando il tuo account chiama POST /v1/orders, la piattaforma riconosce l'account a partire dalla chiave usata nell'header Authorization, individua il livello a cui l'account appartiene per quel prodotto, e applica il prezzo del livello. Se quel prezzo è stato impostato, l'ordine viene creato normalmente con unit_price_eur pari al prezzo del livello. Se non è stato impostato, l'ordine non viene creato e l'API risponde con un errore HTTP 409.

Scenario completo con valori reali

Vediamo lo scenario passo per passo. Account A è un sotto-account che appartiene a un gruppo amministrato da Account B. Nel catalogo, il prodotto «Pacchetto eSIM 10 GB» ha un prezzo di riferimento di 6,50 €. Account B ha però impostato, dal pannello, un prezzo di 7,77 € per il livello a cui Account A appartiene su questo prodotto. Account A chiama l'API con la propria chiave.

Passo 1. Account A consulta il catalogo. Il prodotto compare con il prezzo di riferimento del catalogo (6,50 €), che è uguale per tutti.

{
  "products": [
    {
      "product_id": "e9e3cce1-...",
      "name": "Pacchetto eSIM 10 GB",
      "data_gb": 10,
      "price_eur": 6.50
    }
  ]
}

Passo 2. Account A crea un ordine per una unità del prodotto, esattamente come farebbe un account non in gruppo.

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
  }'

Passo 3. L'API risponde con i dati dell'ordine. Nel blocco order, il campo unit_price_eur è 7,77 €, cioè il prezzo del livello di Account A, non i 6,50 € del catalogo.

{
  "order": {
    "id": "...",
    "order_number": "ORD-2026-000087",
    "status": "processing",
    "environment": "test",
    "product_name": "Pacchetto eSIM 10 GB",
    "quantity": 1,
    "unit_price_eur": 7.77,
    "total_price_eur": 7.77,
    "created_at": "2026-05-28T10:00:00Z"
  },
  "plafond": [
    {
      "resource_type": "data_mb",
      "consumed": 10240,
      "new_balance": 204800
    }
  ],
  "fulfillment": {
    "status": "processing",
    "provider_order_id": "...",
    "error": null
  }
}

I campi prezzo da osservare nella risposta sono questi:

Il prezzo applicato all'ordine di Account A è 7,77 € perché è il prezzo del livello impostato per Account A; il valore 6,50 € del catalogo resta un riferimento e non viene usato per la fatturazione.

Quando il prezzo del livello non è impostato

Se l'account principale non ha ancora impostato un prezzo del livello per il tuo account su un determinato prodotto, POST /v1/orders non crea l'ordine e risponde con HTTP 409 e il codice di errore level_price_not_set.

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": "level_price_not_set"
}

Questo errore segnala una situazione operativa, non un bug nella tua integrazione: significa che il prezzo del prodotto per il tuo livello deve essere impostato dall'account principale, dal pannello, prima che tu possa creare l'ordine. Non c'è nulla che tu possa correggere a livello di chiamata API.

Cosa non cambia

Per chiudere, un breve riepilogo di tutto ciò che resta identico a un'integrazione standard, così non rischi di cercare differenze dove non ce ne sono:

• Gli endpoint sono gli stessi: GET /v1/me, GET /v1/catalog, POST /v1/orders, GET /v1/orders, GET /v1/orders/{id}.
• L'autenticazione è la stessa: header Authorization: Bearer ... con la chiave del tuo account e i suoi scope read/write.
• Il ciclo di vita dell'ordine è lo stesso: stati pending → processing → completed (o failed), come descritto nella pagina «Ciclo di vita dell'ordine».
• Il recupero dell'eSIM (ICCID, codice di attivazione, QR code) avviene esattamente come per un account non in gruppo.