Informacje rozliczeniowe
Na tej stronie
Zarządzanie rozliczeniami przez API
Sekcja Billing w Management API pozwala programowo pobierać i aktualizować dane rozliczeniowe, fetchować faktury oraz monitorować wydatki. Koniec ze skakaniem między konsolą a innymi narzędziami, by sprawdzić status płatności.
Pobieranie informacji rozliczeniowych
Dane rozliczeniowe wydają się niegroźne, dopóki księgowość nie odrzuci faktury przez błędną nazwę firmy lub brak numeru VAT. Weryfikacja tych danych przez API zajmuje jedno żądanie i zapobiega błędom, których nie da się naprawić: jak wyjaśnia uwaga poniżej, nie wygenerujesz ponownie wystawionej faktury z nowymi danymi.
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/billing-info" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Odpowiedź zawiera zarejestrowane dane rozliczeniowe: nazwę firmy, adres, kraj oraz – w stosownych przypadkach – numer VAT.
Aktualizacja danych
Aby zmodyfikować informacje rozliczeniowe:
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"
}'
Ważna uwaga dotycząca istniejących faktur
Zaktualizowane dane rozliczeniowe obowiązują wyłącznie dla przyszłych faktur. Nie możesz cofnąć się w czasie i wygenerować ponownie faktury z nowymi danymi. Zweryfikuj swoje informacje przed zakończeniem cyklu rozliczeniowego, aby mieć pewność, że faktury będą poprawne.
Pobieranie faktur
Endpoint GET /v1/billing/teams/{teamId}/invoices zwraca historię Twoich faktur:
# Faktury za konkretny miesią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 danego miesiąca
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/invoices?since.year=2026&since.month=1" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Parametry filtrowania
- billingCycle.year i billingCycle.month: pobierz faktury za konkretny cykl rozliczeniowy
- since.year i since.month: pobierz wszystkie faktury od danego miesiąca
Statusy faktur
Spośród tych czterech statusów tylko jeden wymaga natychmiastowej reakcji. FAILED oznacza, że obciążenie nie przeszło – wygasła karta, osiągnięto limit, trwa spor – a nieopłacona faktura prowadzi ostatecznie do zawieszenia usługi. To właśnie ten status musisz monitorować automatycznie, jak pokazano w lekcji o metodach płatności; pozostałe trzy jedynie przeglądasz, ale alert ustawiasz tylko na ten.
- PENDING: faktura jest przetwarzana; płatność nie została jeszcze pobrana
- PAID: płatność zakończona sukcesem
- FAILED: obciążenie nie powiodło się (wygasła karta, niewystarczające środki itp.)
- WILL_NEVER_BE_CHARGED: faktura nigdy nie zostanie obciążona (kredyt, korekta)
Logika rozliczeń xAI
Zrozumienie interakcji między dwoma trybami zapobiega błędnym interpretacjom dashboardu. Kredyty prepaid są wykorzystywane w pierwszej kolejności; rozliczenie miesięczne uruchamia się dopiero po wyczerpaniu salda. Zerowe saldo przy aktywnej usłudze nie jest anomalią: oznacza to, że konsumujesz w modelu postpaid, a faktura końcowomiesięczna narasta.
Kredyty prepaid
Zakupione kredyty są pobierane natychmiast w momencie zakupu. Każde wywołanie API zużywa kredyty proporcjonalnie do liczby przetworzonych tokenów. Kredyty mają priorytet.
Rozliczenie miesięczne (postpaid)
Jeśli Twoje kredyty się wyczerpały lub ich nie masz, zużycie jest rozliczane na koniec miesiąca. Koszt każdego wywołania API jest obliczany natychmiast, ale obciążenie następuje na koniec cyklu.
Różnice w zliczaniu tokenów
Spodziewaj się rozbieżności między lokalnym zliczaniem a liczbą użytą do rozliczeń – lepiej dowiedzieć się o tym wcześniej, niż tracić pół dnia na dochodzenie. Rozliczenia są wiążące: swoje szacunki kosztów opieraj na danych z Analytics API, nigdy na zliczaniu wykonanym klientowym tokenizarem. To normalne: endpointy wnioskowania dodają wewnętrzne tokeny do przetwarzania (instrukcje systemowe, formatowanie), co nieznacznie zwiększa liczbę tokenów objętych opłatą w porównaniu z surowym tekstem.
Podgląd bieżących obciążeń
Aby zobaczyć narosłe obciążenia przed końcem cyklu:
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/invoice/preview" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Ten podgląd to jedyny sposób, by poznać bieżącą kwotę przed wystawieniem faktury. Sprawdzany raz w tygodniu zamienia rozliczenie miesięczne w coś, co da się kontrolować: widzisz dryf kosztów w połowie cyklu, gdy masz jeszcze czas, by przekierować ruch do tańszego modelu lub obniżyć limit.
Kluczowe wnioski
- Używaj
GETiPOSTna/v1/billing/teams/{teamId}/billing-info, aby pobrać i zmodyfikować dane - Faktury mają 4 statusy: PENDING, PAID, FAILED, WILL_NEVER_BE_CHARGED
- Zmiany rozliczeniowe nie działają wstecz na istniejące faktury
- xAI łączy kredyty prepaid (priorytet) z rozliczeniem miesięcznym
- Podgląd obciążeń (
invoice/preview) pozwala przewidzieć koszty