Informazioni di fatturazione
In questa pagina
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.
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
GETePOSTsu/v1/billing/teams/{teamId}/billing-infoper 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