Fakturační údaje
Na této stránce
Správa fakturace prostřednictvím API
Sekce Fakturace v Management API ti umožňuje programově získávat a aktualizovat fakturační údaje, stahovat faktury a sledovat výdaje. Už žádné přepínání mezi konzolí a kontrolou stavu plateb.
Načtení fakturačních údajů
Fakturační detaily se mohou zdát neškodné, dokud účetnictví neodmítne fakturu kvůli špatnému názvu firmy nebo chybějícímu DIČ. Ověření těchto údajů přes API zabere jeden požadavek a předejde neopravitelné chybě: jak vysvětluje poznámka níže, vystavenou fakturu s novými údaji již nelze vygenerovat znovu.
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/billing-info" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Odpověď obsahuje registrované fakturační údaje: název společnosti, adresu, zemi a případně DIČ.
Aktualizace údajů
Pro úpravu fakturačních informací použij:
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"
}'
Důležitá poznámka k existujícím fakturám
Aktualizované fakturační údaje se projeví pouze u budoucích faktur. Nelze zpětně vygenerovat fakturu s novými údaji. Své informace si ověř před skončením fakturačního cyklu, aby byly faktury správné.
Načtení faktur
Koncový bod GET /v1/billing/teams/{teamId}/invoices vrací historii tvých faktur:
# Faktury za konkrétní měsíc
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/invoices?billingCycle.year=2026&billingCycle.month=3" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
# Faktury od daného měsíce
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/invoices?since.year=2026&since.month=1" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Filtrační parametry
- billingCycle.year a billingCycle.month: načte faktury za konkrétní cyklus
- since.year a since.month: načte všechny faktury od daného měsíce
Stavy faktur
Ze těchto čtyř stavů vyžaduje okamžitou akci pouze jeden. Stav FAILED znamená, že platba neproběhla – vypršela karta, dosažen limit nebo vznikl spor – a nezaplacená faktura nakonec vede k pozastavení služby. Toto je stav, který musíš automaticky monitorovat, jak ukazuje lekce o platebních metodách; ostatní tři stavy pouze kontroluješ, ale na tento nastavuješ alert.
- PENDING: faktura se zpracovává; platba ještě nebyla stržena
- PAID: platba byla úspěšná
- FAILED: stržení platby selhalo (vypršela karta, nedostatek prostředků atd.)
- WILL_NEVER_BE_CHARGED: faktura nikdy nebude zpoplatněna (dobropis, úprava)
Logika fakturace xAI
Pochopení interakce mezi oběma režimy předejde nesprávné interpretaci tvého dashboardu. Předplacené kredity se čerpají jako první; měsíční fakturace se aktivuje až po vyčerpání zůstatku. Nulový zůstatek při aktivní službě není anomálie: znamená to, že nyní spotřebováváš na postpaid bázi a koncem měsíce se ti vystaví faktura.
Předplacené kredity
Zakoupené kredity jsou strženy okamžitě při nákupu. Každé volání API spotřebovává kredity na základě počtu zpracovaných tokenů. Kredity se čerpají jako první.
Měsíční fakturace (postpaid)
Pokud jsou tvé kredity vyčerpané nebo žádné nemáš, je spotřeba fakturována na konci měsíce. Náklady na každé volání API se vypočítají okamžitě, ale stržení proběhne až na konci cyklu.
Rozdíly v počítání tokenů
Počítej s rozdílem mezi tvým lokálním počtem a fakturačním počtem a je lepší to vědět předem, než strávit půl dne hledáním příčiny. Rozhodující je fakturace: své odhady nákladů zakládej na údajích z Analytics API, nikdy na počtu získaném tokenizérem na straně klienta. Je to normální: inferenční koncové body přidávají pro zpracování interní tokeny (systémové instrukce, formátování), což mírně zvyšuje fakturovaný počet oproti čistému textu.
Zobrazení aktuálních poplatků
Pro zobrazení nashromážděných poplatků před koncem cyklu použij:
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/invoice/preview" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Tento náhled je jediným způsobem, jak zjistit aktuální částku před vystavením faktury. Pokud jej kontroluješ jednou týdně, změníš měsíční fakturaci na něco zvládnutelného: uprostřed cyklu uvidíš odklon v nákladech, kdy je ještě čas přesměrovat provoz na levnější model nebo snížit limit.
Klíčové poznatky
- Použij
GETaPOSTna/v1/billing/teams/{teamId}/billing-infopro načtení a úpravu údajů - Faktury mají 4 stavy: PENDING, PAID, FAILED, WILL_NEVER_BE_CHARGED
- Změny ve fakturaci nejsou zpětné pro existující faktury
- xAI kombinuje předplacené kredity (priorita) a měsíční fakturaci
- Náhled poplatků (
invoice/preview) ti umožní předvídat náklady