Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Informazioni di fatturazione

Lezione 5 di 14 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Gestire la fatturazione tramite API
  2. Recuperare le informazioni di fatturazione
  3. Aggiornare le informazioni
  4. Recuperare le fatture
  5. Logica di fatturazione xAI
  6. Visualizzare gli addebiti correnti
  7. Punti chiave

Gestire la fatturazione tramite API

La sezione Fatturazione delle API di Management ti consente di recuperare e aggiornare le tue informazioni di fatturazione, ottenere le fatture e monitorare la spesa, il tutto in modo programmatico. Niente più salti avanti e indietro verso la console per verificare lo stato dei pagamenti.

GET
Recupera
POST
Aggiorna
4
Stati della fattura
Mensile
Ciclo di fatturazione

Recuperare le informazioni di fatturazione

I dettagli di fatturazione sembrano innocui finché la contabilità non respinge una fattura a causa di un nome errato o di un numero di partita IVA mancante. Verificarli tramite API richiede una sola richiesta ed evita un errore irreparabile: come spiega la nota qui sotto, non puoi rigenerare una fattura già emessa con nuovi dettagli.

curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/billing-info" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

La risposta contiene i dettagli di fatturazione registrati: ragione sociale, indirizzo, paese e numero di partita IVA, se applicabile.

Aggiornare le informazioni

Per modificare le tue informazioni di fatturazione:

curl -X POST "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/billing-info" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companyName": "My Company SAS",
    "address": "15 Peace Street",
    "city": "Paris",
    "country": "FR",
    "vatNumber": "FR12345678901"
  }'

Nota importante sulle fatture esistenti

Le informazioni di fatturazione aggiornate si applicano solo alle fatture future. Non puoi rigenerare retroattivamente una fattura con nuovi dettagli. Verifica le tue informazioni prima della fine del ciclo di fatturazione per garantire fatture accurate.

Recuperare le fatture

L’endpoint GET /v1/billing/teams/{teamId}/invoices restituisce la cronologia delle tue fatture:

# Fatture per un mese specifico
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/invoices?billingCycle.year=2026&billingCycle.month=3" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

# Fatture da un dato mese in poi
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/invoices?since.year=2026&since.month=1" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Parametri di filtro

  • billingCycle.year e billingCycle.month: recupera le fatture per un ciclo specifico
  • since.year e since.month: recupera tutte le fatture da un dato mese in poi

Stati della fattura

Di questi quattro stati, solo uno richiede un’azione immediata. FAILED significa che l’addebito non è andato a buon fine (carta scaduta, limite raggiunto, contestazione) e una fattura non pagata porta infine alla sospensione del servizio. Questo è lo stato che devi monitorare automaticamente, come mostrato nella lezione sui metodi di pagamento; rivedi gli altri tre, ma genera alert solo per questo.

  • PENDING: la fattura è in elaborazione; il pagamento non è ancora stato addebitato
  • PAID: il pagamento è andato a buon fine
  • FAILED: l’addebito è fallito (carta scaduta, fondi insufficienti, ecc.)
  • WILL_NEVER_BE_CHARGED: la fattura non verrà mai addebitata (credito, rettifica)

Logica di fatturazione xAI

Comprendere come interagiscono le due modalità previene interpretazioni errate della tua dashboard. I crediti prepagati vengono utilizzati per primi; la fatturazione mensile scatta solo una volta esaurito il saldo. Un saldo zero con servizio attivo non è un’anomalia: significa che stai ora consumando in modalità postpagata e la fattura di fine mese si sta accumulando.

Crediti prepagati

I crediti acquistati vengono addebitati immediatamente al momento dell’acquisto. Ogni chiamata API consuma crediti in base al numero di token elaborati. I crediti vengono utilizzati per primi.

Fatturazione mensile (postpagata)

Se i tuoi crediti sono esauriti o non ne possiedi, il consumo viene fatturato alla fine del mese. Il costo di ogni chiamata API è calcolato immediatamente, ma l’addebito avviene alla fine del ciclo.

Differenze nel conteggio dei token

Aspettati una discrepanza tra il tuo conteggio locale e quello di fatturazione; è meglio saperlo prima di perdere mezza giornata a cercarne la causa. La fatturazione fa fede: basa le tue stime dei costi sui dati delle API di analytics, mai su un conteggio eseguito con un tokenizzatore lato client. Questo è normale: gli endpoint di inferenza aggiungono token interni per l’elaborazione (istruzioni di sistema, formattazione), il che aumenta leggermente il conteggio fatturato rispetto al testo grezzo.

Visualizzare gli addebiti correnti

Per visualizzare gli addebiti accumulati prima della fine del ciclo:

curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/invoice/preview" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Questa anteprima è l’unico modo per conoscere l’importo corrente prima dell’emissione della fattura. Controllata una volta a settimana, trasforma la fatturazione mensile in qualcosa di gestibile: vedi la deriva dei costi a metà percorso, quando c’è ancora tempo per instradare il traffico verso un modello più economico o abbassare un limite.

Punti chiave

  • GET e POST su /v1/billing/teams/{teamId}/billing-info per recuperare e modificare le informazioni
  • Le fatture hanno 4 stati: PENDING, PAID, FAILED, WILL_NEVER_BE_CHARGED
  • Le modifiche alla fatturazione non sono retroattive sulle fatture esistenti
  • xAI combina crediti prepagati (prioritari) e fatturazione mensile
  • L’anteprima degli addebiti (invoice/preview) ti consente di anticipare i costi