Informații de facturare
Pe această pagină
Gestionarea facturării prin API
Secțiunea de facturare din Management API vă permite să preluați și să actualizați informațiile de facturare, să descărcați facturile și să monitorizați cheltuielile, totul în mod programatic. Nu mai este nevoie să navigați constant între consolă pentru a verifica starea plăților.
Preluarea informațiilor de facturare
Detaliile de facturare pot părea inofensive până când departamentul de contabilitate respinge o factură din cauza unui nume incorect sau a lipsei codului de TVA. Verificarea acestora prin API necesită o singură cerere și previne o eroare iremediabilă: așa cum explică nota de mai jos, nu puteți regenera o factură emisă cu detalii noi.
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/billing-info" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Răspunsul conține detaliile de facturare înregistrate: denumirea companiei, adresa, țara și codul de TVA, dacă este cazul.
Actualizarea informațiilor
Pentru a modifica informațiile de facturare:
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"
}'
Notă importantă privind facturile existente
Informațiile de facturare actualizate se aplică doar facturilor viitoare. Nu puteți regenera retroactiv o factură cu detalii noi. Verificați-vă informațiile înainte de încheierea ciclului de facturare pentru a asigura exactitatea facturilor.
Preluarea facturilor
Endpoint-ul GET /v1/billing/teams/{teamId}/invoices returnează istoricul facturilor dumneavoastră:
# Facturi pentru o lună specifică
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/invoices?billingCycle.year=2026&billingCycle.month=3" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
# Facturi începând cu o lună dată
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 de filtrare
- billingCycle.year și billingCycle.month: preluați facturile pentru un ciclu specific
- since.year și since.month: preluați toate facturile începând cu o lună dată
Stările facturilor
Dintre aceste patru stări, doar una necesită o acțiune imediată. FAILED înseamnă că debitarea nu a reușit – card expirat, limită atinsă, contestare – iar o factură neplătită duce în cele din urmă la suspendarea serviciului. Aceasta este starea pe care trebuie să o monitorizați automat, așa cum se arată în lecția despre metodele de plată; le revizuiți pe celelalte trei, dar generați alerte doar pentru aceasta.
- PENDING: factura este în curs de procesare; plata nu a fost încă debitată
- PAID: plata a fost efectuată cu succes
- FAILED: debitarea a eșuat (card expirat, fonduri insuficiente etc.)
- WILL_NEVER_BE_CHARGED: factura nu va fi niciodată debitată (credit, ajustare)
Logica de facturare xAI
Înțelegerea modului în care interacționează cele două moduri previne interpretările eronate ale tabloului de bord. Creditele prepaid sunt utilizate primele; facturarea lunară intervine doar după epuizarea soldului. Un sold zero cu serviciul activ nu este o anomalie: înseamnă că consumați acum în regim postpaid, iar factura de sfârșit de lună se acumulează.
Credite prepaid
Creditele achiziționate sunt facturate imediat la momentul cumpărării. Fiecare apel API consumă credite în funcție de numărul de tokeni procesați. Creditele sunt utilizate cu prioritate.
Facturare lunară (postpaid)
Dacă creditele dumneavoastră sunt epuizate sau nu aveți niciunul, consumul este facturat la sfârșitul lunii. Costul fiecărui apel API este calculat imediat, dar debitarea are loc la sfârșitul ciclului.
Diferențe în numărarea tokenilor
Așteptați-vă la o discrepanță între numărarea locală și cea de facturare; este mai bine să știți acest lucru înainte de a pierde jumătate de zi investigând cauza. Facturarea este autoritativă: bazați-vă estimările de cost pe cifrele din Analytics API, niciodată pe o numărare efectuată cu un tokenizator lato-client. Acest lucru este normal: endpoint-urile de inferență adaugă tokeni interni pentru procesare (instrucțiuni de sistem, formatare), ceea ce mărește ușor numărul facturat comparativ cu textul brut.
Vizualizarea taxelor curente
Pentru a vizualiza taxele acumulate înainte de încheierea ciclului:
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/invoice/preview" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Această previzualizare este singura modalitate de a cunoaște suma curentă înainte de emiterea facturii. Verificată o dată pe săptămână, transformă facturarea lunară într-un proces gestionabil: observați devierea costurilor la mijlocul lunii, când mai aveți timp să redirecționați traficul către un model mai ieftin sau să reduceți o limită.
Puncte cheie
- Utilizați
GETșiPOSTpe/v1/billing/teams/{teamId}/billing-infopentru a prelua și modifica informațiile - Facturile au 4 stări: PENDING, PAID, FAILED, WILL_NEVER_BE_CHARGED
- Modificările de facturare nu sunt retroactive pentru facturile existente
- xAI combină creditele prepaid (cu prioritate) și facturarea lunară
- Previzualizarea taxelor (
invoice/preview) vă permite să anticipați costurile