Build a Customer-Facing AI Usage Reporting API for Resellers and SaaS Tenants

Wewnętrzna księga bramy to nie to samo, co raportowanie skierowane do klienta API. Księga jest dowodem na to, co wydarzyło się na Twojej platformie. Raport klienta wyjaśnia, co najemca, klient, obszar roboczy lub klient końcowy może bezpiecznie zobaczyć, zapytać, uzgodnić i wykorzystać przed terminem wystawienia faktury.

To rozróżnienie ma znaczenie dla sprzedawców, agencji, wbudowanych produktów AI i zespołów SaaS, które udostępniają wykorzystanie sztucznej inteligencji swoim klientom. Klienci nie tylko pytają: „Ile wydałem?” Pytają, który klucz, model, punkt końcowy, przepływ pracy, kohorta użytkowników lub przedział czasu spowodowały wydatek; czy numer jest ostateczny; dlaczego faktura różni się od wczorajszego dashboardu; oraz czy w procesie są ujawniane monity lub dane uwierzytelniające dostawcy.

Praktyczną odpowiedzią jest opublikowanie stabilnego raportu API użycia AI API wspartego niezmiennymi zdarzeniami użycia, cenami opartymi na wersjach, tokenami dostępu o określonym zakresie i punktami końcowymi uzgadniania. API powinno być nudne, wyraźne i trudne do błędnej interpretacji.

Zdefiniuj kontrakt raportowania przed modelem danych

Zacznij od problemu klienta, a nie od schematu przechowywania. Raport API powinien odpowiadać na cztery pytania:

• Z czego korzystał ten najemca?
• Ile to kosztowało zgodnie z zasadami cenowymi widocznymi dla klienta?
• Czy liczba jest szacunkowa, dostosowana czy ostateczna?
• Jak to się łączy z fakturami, kredytami, doładowaniami lub marżą partnera?

Różni się to od wewnętrznego panelu operacyjnego. Systemy wewnętrzne mogą ujawniać identyfikatory żądań dostawców, decyzje dotyczące routingu, nieprzetworzone ładunki błędów, stan ponownych prób lub nazwy pul danych uwierzytelniających. Strona skierowana do klienta API powinna udostępniać tylko pola potrzebne do atrybucji, wyjaśnienia kosztów, audytu i analityki produktu.

Fakt: dostawcy sztucznej inteligencji i systemy rozliczeniowe udostępniają dane o użytkowaniu i kosztach za pomocą różnych nazw pól, opcji grupowania i zachowań agregacyjnych. Niektóre interfejsy API użytkowania grupują według wymiarów, takich jak model, obszar roboczy, klucz lub warstwa usług; inne powierzchnie różnią się w zależności od typu punktu końcowego. Brama powinna to znormalizować przed opublikowaniem raportów klientów.

Zalecenie: Potraktuj raport API jako umowę dotyczącą produktu. Wersjonuj go od pierwszego wydania, nawet jeśli pierwsza wersja ma tylko kilka punktów końcowych.

Użyj wymiarów o zasięgu najemcy

Raportowanie API powinno uniemożliwić ominięcie granic najemców. Każde zapytanie musi zostać rozwiązane w zakresie autoryzowanego dzierżawcy, zanim dotknie danych o użyciu.

Przydatne wymiary obejmują:

• customer_id: dalszy klient lub najemca.
• project_id: aplikacja, środowisko, zespół lub przestrzeń robocza wewnątrz klienta.
• api_key_id: klucz wydany przez bramę, nigdy klucz dostawcy nadrzędnego.
• model_alias: nazwa modelu lub profil widoczna dla klienta.
• provider: opcjonalne i tylko wtedy, gdy ujawnienie wyboru dostawcy stanowi część umowy.
• endpoint_family: czat, odpowiedzi, osadzanie, obrazy, dźwięk, zbiorcze, w czasie rzeczywistym, narzędzia lub inna stabilna kategoria.
• workflow_tag: tag dostarczony przez klienta, taki jak bot wsparcia, parser faktur, agent kodujący lub qa-eval.
• user_hash: pseudonimowy identyfikator użytkownika końcowego umożliwiający przypisanie bez domyślnego ujawniania danych osobowych.
• time_bucket: limity godzinowe, dzienne, miesięczne lub niestandardowe interwałów.

W przypadku sprzedawców i agencji ta umowa dotycząca raportowania znajduje się blisko powierzchni udostępniania partnerów. Jeśli klienci i klucze są tworzeni poprzez automatyzację APIpartnera, raportowanie użycia powinno używać tych samych identyfikatorów klienta i kluczy, a nie wymyślać drugi system nazewnictwa.

Oddzielnie eksponuj jednostki wykorzystania i pola pieniężne

Dobry raport oddziela wykorzystanie fizyczne od cen. Tokeny, wywołania narzędzi, obrazy, sekundy audio i zadania wsadowe to nie pieniądze. Pieniądze są obliczane na podstawie wykorzystania, zasad cenowych, rabatów, kredytów, marży i korekt.

Każdy wiersz zbiorczy powinien zawierać co najmniej pola takie jak:

{
  "bucket_start": "2026-09-01T00:00:00Z",
  "bucket_end": "2026-09-02T00:00:00Z",
  "customer_id": "cus_123",
  "project_id": "proj_support",
  "api_key_id": "key_789",
  "model_alias": "support-fast",
  "endpoint_family": "chat",
  "request_count": 18420,
  "input_tokens": 9821000,
  "cached_input_tokens": 2410000,
  "output_tokens": 1268000,
  "reasoning_tokens": 310000,
  "tool_calls": 860,
  "estimated_cost": "142.36",
  "settled_cost": "141.91",
  "currency": "USD",
  "pricing_catalog_version": "2026-09-01",
  "invoice_status": "pending"
}

Nie ukrywaj kategorii tokenów tylko dlatego, że faktura jest denominowana w pieniądzu. Klienci potrzebują pól jednostek do debugowania zachowania. Tokeny wejściowe w pamięci podręcznej, tokeny wnioskowania, opłaty za narzędzia hostowane i jednostki multimedialne często wyjaśniają, dlaczego dwa podobne przepływy pracy kosztują różne kwoty.

Zalecenie: przechowuj kwoty dziesiętne jako ciągi znaków w API odpowiedziach. Unikaj wartości zmiennoprzecinkowych w polach kosztów. Użyj pola waluty w każdym wierszu, zamiast zakładać jedną walutę globalną.

Oddzielne wykorzystanie tymczasowe, skorygowane i końcowe

Raporty AI wyświetlane klientom często kończą się niepowodzeniem, ponieważ udają, że każda liczba jest natychmiast ostateczna. W praktyce użycie może się zmienić po zakończeniu pierwszego żądania.

Częste przyczyny to:

• Odpowiedzi przesyłane strumieniowo, gdy klient rozłącza się, zanim dostawca powróci do ostatecznego użycia.
• Opóźnione użycie przez dostawcę narzędzi wsadowych, multimediów lub hostowanych.
• Ponowne próby, gdy aplikacja widzi jedno logiczne żądanie, ale brama widzi wiele płatnych prób.
• Zwroty pieniędzy, kredyty, korekty cen lub wycofanie oszustw.
• Zmiany aliasów modeli, gdy nazwy widoczne dla klienta różnią się od identyfikatorów modeli wcześniejszych.

Nie nadpisuj po cichu wierszy w sposób uniemożliwiający wyjaśnienie wczorajszej odpowiedzi API. Zamiast tego opublikuj model stanu:

• provisional: obliczone na podstawie szacunków bramy lub częściowych danych dostawcy.
• settled: obliczone na podstawie znormalizowanego wykorzystania dostawcy i aktywnego katalogu cen.
• adjusted: zmieniono w wyniku późniejszej korekty, uznania, zwrotu pieniędzy lub uzgodnienia.
• invoiced: zawarte w widocznej dla klienta fakturze lub wyciągu.

Nieprzetworzone zdarzenia użycia powinny być niezmienne. Korekty powinny pojawiać się jako wiersze korekty powiązane z pierwotnym zdarzeniem lub okresem zbiorczym.

{
  "adjustment_id": "adj_456",
  "original_event_id": "evt_abc",
  "customer_id": "cus_123",
  "reason": "provider_usage_correction",
  "cost_delta": "-0.45",
  "currency": "USD",
  "created_at": "2026-09-03T10:15:00Z"
}

Kompromis: Raportowanie w czasie zbliżonym do rzeczywistego jest lepsze w przypadku alertów budżetowych i zaufania klientów, ale wymaga widocznych stanów tymczasowych. Raportowanie zawierające wyłącznie sfinalizowane dane jest łatwiejsze do uzgodnienia, ale jest znacznie mniej przydatne, gdy klienci próbują powstrzymać nadmierne wydatki przed otrzymaniem faktury.

Zapewnij dostęp do agregatów i nieprzetworzonych zdarzeń

Jeden punkt końcowy nie może obsłużyć każdego przypadku użycia. Deski rozdzielcze wymagają tanich agregatów. Zespoły finansowe i klienci korporacyjni mogą potrzebować dowodów na poziomie wiersza.

Praktyczny raport API zwykle ma co najmniej trzy rodziny punktów końcowych:

GET /v1/usage/summary
GET /v1/usage/events
GET /v1/usage/reconciliation

Podsumowanie punktu końcowego

Podsumowujący punkt końcowy powinien zwracać wstępnie zagregowane wykorzystanie według małego zestawu wymiarów i przedziałów czasu.

GET /v1/usage/summary?customer_id=cus_123&from=2026-09-01T00:00:00Z&to=2026-09-08T00:00:00Z&bucket=day&group_by=model_alias,api_key_id

Użyj go do pulpitów nawigacyjnych, stron budżetu i zestawień kosztów dostępnych dla klientów. Powinien być wystarczająco szybki, aby móc wielokrotnie wywoływać bez skanowania nieprzetworzonej tabeli zdarzeń. Jeśli produkt zawiera pulpit nawigacyjny analizy użycia AI API, tym punktem końcowym jest zazwyczaj umowa zaplecza, która zapewnia spójność interfejsu użytkownika z wyeksportowanymi raportami.

Punkt końcowy zdarzeń

Punkt końcowy zdarzeń powinien udostępniać niezmienne rekordy użycia z podziałem kursora na strony. Używaj go w przypadku klientów wymagających dużej liczby audytów, dochodzeń w ramach pomocy technicznej i eksportu magazynów.

GET /v1/usage/events?customer_id=cus_123&from=2026-09-01T00:00:00Z&limit=500&cursor=eyJpZCI6...

Każdy wiersz powinien zawierać stabilny event_id, znaczniki czasu, rodzinę żądań, alias modelu, identyfikator klucza, znormalizowane jednostki użycia, pola kosztów i stan. Domyślnie nie powinien zawierać surowych podpowiedzi ani uzupełnień.

Punkt końcowy uzgadniania

Punkt końcowy uzgadniania łączy użycie z obiektami rozliczeniowymi widocznymi dla klienta.

GET /v1/usage/reconciliation?customer_id=cus_123&invoice_id=inv_2026_09

Zwrot pozycji faktury, sumy wykorzystania, zastosowane środki, doładowania, podatki, jeśli mają zastosowanie, zasady marży partnera, jeśli są widoczne dla klienta, oraz wszelkie korekty wprowadzone po pierwszym oszacowaniu. W tym miejscu raportowanie użytkowania staje się łatwym do wyjaśnienia rozliczeniem, a nie stosem liczników.

Zalecenie: Staraj się, aby faktury i raporty użytkowania były powiązane, ale nie identyczne. Użycie API wyjaśnia zużycie. Faktura zawiera informację o należnych kwotach. Powinny one być uzgadniane poprzez stabilne identyfikatory, a nie skupiać się w jednym przeciążonym punkcie końcowym.

Użyj Cursor paginacji i stabilnej kolejności

Paginacja offsetowa jest niestabilna w przypadku zdarzeń związanych z użytkowaniem, ponieważ w trakcie paginacji klienta mogą pojawić się nowe rekordy i korekty z opóźnieniem. Użyj paginacji kursora ze stabilnym sortowaniem.

Trwały wzór to:

• Sortuj według event_time i event_id.
• Wróć next_cursor, gdy istnieje więcej rekordów.
• Ustaw kursory jako nieprzezroczyste.
• Udokumentuj, czy spóźnione zdarzenia mogą pojawiać się w już przeczytanych oknach.
• Udostępnij filtr updated_since dla zadań uzgadniania.

W przypadku zagregowanych punktów końcowych klienci mogą chcieć powtarzalnych raportów. Obsługa parametru finalized_before lub report_version, aby można było konsekwentnie powtarzać eksporty finansowe.

GET /v1/usage/summary?customer_id=cus_123&month=2026-09&status=finalized&report_version=2026-10-02

Przewidywanie: Schematy raportowania dotyczące wykorzystania sztucznej inteligencji będą się zmieniać w miarę dodawania przez dostawców nowych typów tokenów, opłat za narzędzia, poziomów usług i jednostek rozliczeniowych za media. Wersjonowane umowy dotyczące raportów będą starzeć się lepiej niż punkty końcowe, które ujawniają wszystko, co zawiera bieżąca odpowiedź dostawcy.

Cena wersji i schemat łącznie

Pola użytkowania i reguły cenowe zmieniają się niezależnie. Model może zyskać ceny tokenów buforowanych. Dostawca może wprowadzić kontrole oparte na tokenach rozumowania. Sprzedawca może zmienić zasady marży dla nowych klientów, honorując jednocześnie stare umowy.

Każdy wiersz kosztów powinien zawierać:

• pricing_catalog_version
• schema_version
• rate_effective_at
• currency
• cost_basis: szacunkowe, rozliczone, skorygowane, zafakturowane

Jest to szczególnie ważne, gdy platforma oferuje ujednoliconą sztuczną inteligencję API rozliczenia dla wielu dostawców modeli. Pojedynczy rachunek jest przydatny tylko wtedy, gdy klienci rozumieją, w jaki sposób heterogeniczne wykorzystanie zostało znormalizowane w spójne kategorie kosztów.

Fakt: Otwarte schematy kosztów i użytkowania ewoluują, aby objąć sztuczną inteligencję, chmurę, SaaS, centra danych i innych dostawców technologii. Wspiera to podejście wersjonowane, a nie kodowanie na stałe jednego, trwałego kształtu eksportu.

Zaprojektuj kontrolę dostępu jako część API

Dane dotyczące użytkowania są poufne. Może ujawnić wzrost liczby klientów, premiery produktów, nieudaną automatyzację, przypadki nadużyć lub wewnętrzne przepływy pracy. Kontrola dostępu powinna być częścią projektu raportowania, a nie refleksją.

Jasno zdefiniuj role:

• customer_admin: może wyświetlić całe wykorzystanie w zakresie swojego klienta.
• project_admin: może przeglądać wykorzystanie przypisanych projektów.
• billing_viewer: umożliwia przeglądanie uzgodnień kosztów i faktur, ale nie zestawień na poziomie użytkownika.
• support_operator: może pobrać wąskie wycinki dla zgłoszenia do pomocy technicznej, korzystając z rejestrowania kontroli.
• partner_operator: domyślnie można wyświetlić przypisanych najemców, a nie każdego dzierżawcę.

Użyj tokenów o określonym zakresie w celu uzyskania dostępu do komputera. Token, który może wysyłać zapytania o użycie dla cus_123, nie powinien mieć możliwości zmiany kluczy, modyfikowania cen ani odczytywania użycia innego klienta na podstawie zgadywania identyfikatorów.

Zdecyduj także, które wymiary mają wpływ na prywatność. Pole user_hash może być bezpieczne dla niektórych klientów i zbyt odkrywcze dla innych. Tagi przepływu pracy mogą powodować wyciek z kontekstu biznesowego, jeśli klienci umieścili w metadanych nazwy takie jak cel przejęcia lub ocena prawna. Jasne zachowanie i redagowanie dokumentów.

Lista kontrolna minimalnego wdrożenia

Użyj tej sekwencji, aby uniknąć tworzenia raportu API, który wygląda na kompletny, ale którego nie można pogodzić.

1. Utwórz niezmienne zdarzenia użycia. Przypisz każdemu zdarzeniu podlegającemu rozliczeniu stabilny identyfikator, zakres dzierżawy, rodzinę żądań, alias modelu, znormalizowane jednostki, znaczniki czasu i stan źródła.
2. Normalizacja wykorzystania dostawcy w jednostkach wewnętrznych. W razie potrzeby przechowuj surowe ładunki dostawcy wewnętrznie, ale udostępniaj stabilne pola klientów.
3. Zastosuj wersjonowany katalog cen. Przechowuj wersję katalogu używaną przy każdym oszacowaniu, rozliczeniu i korekcie.
4. Urzeczywistniaj agregacje godzinowe i dzienne. Nie wykonuj zapytań do panelu kontrolnego, skanujących surowe zdarzenia w skali klienta.
5. Dodaj wiersze korekty. Nigdy nie ukrywaj poprawek poprzez mutację starych sum kosztów bez wyjaśnienia.
6. Twórz eksporty zdarzeń podzielone na strony kursorem. Uwzględnij nieprzezroczyste kursory, stabilną kolejność i filtry aktualizowane od czasu.
7. Utwórz uzgodnienie faktur. Połącz wiersze użycia z wierszami faktury, kredytami, doładowaniami i regułami marży.
8. Wymuś autoryzację w zakresie dzierżawy. Sprawdź, czy nie ma uszkodzonej autoryzacji na poziomie obiektu w każdym punkcie końcowym raportu.
9. Opublikuj wersje schematu. Daj klientom możliwość zażądania stabilnego kształtu raportu.
10. Domyślnie brak przechowywania surowych monitów. Raportowanie użycia nie powinno wymagać przechowywania monitów ani zakończenia.

Typowe kompromisy

Najpierw agregacja lub najpierw zdarzenie: Interfejsy API zorientowane na agregację są bezpieczniejsze i tańsze dla większości klientów. Eksport wydarzeń jest skuteczniejszy, ale powoduje większe obciążenia związane z prywatnością, paginacją i obsługą. Oferta jest najpierw agregowana, chyba że kupujący mają wymagania dotyczące audytu.

Ujawnij lub ukryj nazwy dostawców: Ujawnienie dostawców wyższego szczebla może pomóc wyrafinowanym klientom w analizie wydajności i kosztów. Ukrywanie dostawców sprawia, że ​​abstrakcja produktów jest czystsza. Jeśli routing stanowi część Twojej propozycji wartości, rozważ ujawnienie dostawcy jako opcjonalnego wymiaru kontrolowanego przez plan lub rolę.

Szacunki w czasie rzeczywistym lub raporty końcowe: Szacunki w czasie rzeczywistym pomagają klientom działać, zanim wydatki staną się problemem rozliczeniowym. Raporty końcowe są lepsze dla księgowości. Większość dojrzałych systemów potrzebuje obu.

Ścisły schemat finansowy lub schemat przyjazny produktowi: Schematy zorientowane na finanse mogą ograniczyć prace związane z integracją, ale mogą być zbyt ciężkie dla produktu klienta API. Praktycznym kompromisem jest wewnętrzne wykorzystanie pól inspirowanych finansami podczas publikowania prostszego, wersjonowanego schematu klienta.

Wnioski, które można zastosować

Raporty dotyczące wykorzystania sztucznej inteligencji skierowane do klienta API nie powinny ograniczać się do odpowiedzi na temat rozliczeń dostawców ani wewnętrznej tabeli administracyjnej. Powinna to być stabilna umowa, która umożliwi najemcom zrozumienie sposobu użytkowania przed terminem wystawienia faktury, wgłębienie się w odpowiednie wymiary, odróżnienie kosztów tymczasowych od ostatecznych i uzgodnienie opłat bez ujawniania monitów lub danych uwierzytelniających od dostawcy.

Zbuduj pierwszą wersję wokół trzech punktów końcowych: podsumowań, wydarzeń i uzgadniania. Zabezpiecz je niezmiennymi zdarzeniami użycia, wierszami korekt, cenami z wersjami, stronicowaniem kursora i tokenami dostępu o zasięgu dzierżawy. Ta podstawa wystarczy do obsługi paneli kontrolnych, eksportu klientów, operacji sprzedawców i sporów dotyczących rozliczeń bez przekształcania każdego pytania dotyczącego faktury w ręczne dochodzenie w ramach pomocy technicznej.

Powiązane lektury

• budowanie niezmiennej sztucznej inteligencji API księgi rozliczeniowej