Zbuduj portal resellerów API AI: udostępnianie najemców, mierzenie wykorzystania, rozliczenia i operacje telegramowe

Jeśli zapewniasz klientom dostęp do sztucznej inteligencji, nie przekazuj im kluczy dostawcy wyższego szczebla. Zbuduj warstwę sprzedawcy, która wydaje klucze dostosowane do klienta, egzekwuje limity dzierżawy przed każdym żądaniem, rejestruje wykorzystanie we własnej księdze i synchronizuje sumy podlegające rozliczeniu z systemem rozliczeniowym.

W tym przewodniku opisano praktyczny model operacyjny interfejsu API AI dla agencji, konsultantów i twórców SaaS. To nie jest studium przypadku klienta. Jest to architektura referencyjna, którą możesz dostosować niezależnie od tego, czy korzystasz z interfejsu API partnera, bramy wewnętrznej czy niestandardowego serwera proxy przed wieloma dostawcami modeli.

Architektura portalu sprzedawcy

Bezpieczny portal sprzedawcy rozdziela cztery obowiązki:

• Administracja partnerów: Twoja wewnętrzna aplikacja do tworzenia klientów, planów, kluczy, limitów i przepływów pracy wsparcia.
• Egzekwowanie żądań: ścieżka bramy, która uwierzytelnia klucze klienta, sprawdza zasady, kieruje żądania i blokuje ruch przekraczający limit.
• Rachunkowość użytkowania: trwała księga, która rejestruje dane wejściowe dotyczące wykorzystania i cen na poziomie żądania.
• Rozliczenia i operacje: zaplanowana synchronizacja faktur, alerty, powiadomienia o rotacji kluczy i eskalacja pomocy technicznej.

Typowy przepływ wygląda następująco:

Aplikacja administratora partnera
  → API partnera
    → zapisy klientów/przestrzeni roboczych
    → Klucze API o zasięgu klienta
    → plan, model, budżet i limity stawek
    → bramka żądania
    → księga użytkowania
    → synchronizacja rozliczeń
    → Bot powiadamiający o telegramie

Fakt: OpenAI zaleca, aby na potrzeby współpracy nie udostępniać kluczy API opartych na użytkownikach, a zamiast tego używać kluczy opartych na projektach, przypisanych członków i odrębnych kluczy z izolowanymi limitami stawek i kontrolą wydatków. Warunki usług OpenAI zabraniają również kupowania, sprzedawania lub przekazywania kluczy API osobom trzecim lub od nich. Fakty te potwierdzają projekt sprzedawcy, w którym dane uwierzytelniające nadrzędne pozostają po stronie serwera, a klienci otrzymują własne klucze podrzędne.

Zalecenie: wydaj jeden klucz niższego szczebla dla każdego klienta, projektu lub środowiska. Nie używaj ponownie jednego klucza klienta dla wielu klientów końcowych. Nie ujawniaj danych uwierzytelniających dostawcy nadrzędnego w dokumentacji, kodzie przeglądarki, aplikacjach mobilnych, dziennikach ani wiadomościach obsługi klienta.

Model danych najemcy

Model najemcy powinien wyraźnie określać izolację. Zapisz co najmniej te pola:

id_partnera
identyfikator_klienta
identyfikator obszaru roboczego
api_key_id
identyfikator_planu
stan_rozliczeń
limit_wydatków
limit_stawki
dozwolone_modele
telegram_chat_id
use_ledger_id
stworzony_at
zaktualizowano_at
odwołany_at

W większym portalu dodaj pola dotyczące salda przedpłaty, waluty, regionu podatkowego, identyfikatora klienta na fakturze, poziomu pomocy, stanu nadużycia i tymczasowych zastąpień.

Przykładowy rekord klienta

{
  "partner_id": "partner_123",
  "customer_id": "customer_acme",
  "workspace_id": "ws_prod",
  "plan_id": "growth_api",
  "billing_status": "aktywny",
  "limit_wydatków": {
    "okres": "miesiąc",
    "hard_cap_usd": 500,
    „alert_thresholds”: [0,5, 0,8, 0,95]
  },
  „limit_rate”: {
    „żądania_na_minutę”: 120,
    „tokens_per_day”: 2000000
  },
  „allowed_models”: [„szybki czat”, „standard rozumowania”],
  "telegram_chat_id": "-1001234567890",
  "usage_ledger_id": "ledger_cust_acme"

Zalecenie: traktuj customer_id, workspace_id i api_key_id jako osobne pojęcia. Klient może mieć wiele obszarów roboczych, a każdy obszar roboczy może wymagać oddzielnych kluczy produkcyjnych, przejściowych i programistycznych. Dzięki temu unieważnianie, debugowanie i przypisywanie użycia jest znacznie łatwiejsze.

Sekwencja wprowadzenia nowego klienta

Niezawodny proces wdrażania jest z założenia nudny. Powinien za każdym razem generować te same zapisy i pozostawiać ścieżkę audytu.

1. Utwórz klienta: nazwa prawna sklepu, osoba kontaktowa ds. rozliczeń, osoba kontaktowa ds. technicznych i właściciel wewnętrzny.
2. Utwórz przestrzeń roboczą: oddziel produkcję od testowania, jeśli klient zintegruje się programowo.
3. Przypisz plan: zdefiniuj uwzględnione modele, znaczniki, częstotliwość rozliczeń i oczekiwania dotyczące wsparcia.
4. Ustaw limity: skonfiguruj limity wydatków, limity żądań, limity tokenów i zasady dotyczące serii.
5. Utwórz klucze API: wydawaj klucze o określonym zakresie dla środowisk klienta.
6. Wyślij instrukcje integracji: podaj podstawowy adres URL, format uwierzytelniania, listę modeli, limity i kanał pomocy.
7. Włącz alerty: połącz Telegram lub inny kanał operacyjny, aby otrzymywać powiadomienia o niskim saldzie, kluczach, przestojach i rozliczeniach.
8. Uruchom żądanie testowe: sprawdź uwierzytelnianie, rejestrację użycia, dostęp do modelu i mapowanie faktur.

Zalecenie: spraw, aby wdrożenie było idempotentne. Jeśli aplikacja administracyjna ponawia operację „utwórz klienta”, nie powinna tworzyć zduplikowanych rekordów rozliczeniowych ani duplikatów kluczy API. Do obsługi połączeń używaj zewnętrznych identyfikatorów i kluczy idempotencji.

Kontrola budżetu w czasie żądania

Najważniejsze egzekwowanie prawa ma miejsce, zanim żądanie dotrze do modelu wyższego szczebla. Twoja brama nie powinna wykryć, że klient przekroczył budżet dopiero po tym, jak dostawca już obciążył Cię opłatą.

Użyj tej sekwencji wstępnej:

1. Uwierzytelnij klucz API dalszego łańcucha.
2. Rozwiąż problemy partner_id, customer_id i workspace_id.
3. Sprawdź, czy klucz jest aktywny i nie został unieważniony.
4. Sprawdź stan rozliczeń: aktywne, próbne, przedpłacone, wstrzymane, zaległe lub zawieszone.
5. Sprawdź twardy limit wydatków w bieżącym okresie rozliczeniowym.
6. Sprawdź limity szybkości, takie jak żądania na minutę i tokeny dziennie.
7. Sprawdź, czy żądany model jest dozwolony w planie klienta.
8. Oszacuj maksymalny możliwy koszt na podstawie modelu, maksymalnej liczby tokenów i parametrów żądania.
9. Przekaż żądanie tylko wtedy, gdy zasady zostaną spełnione.

jeśli klucz.odwołany:
    odrzucić(401, „Klucz API unieważniony”)
jeśli status_rozliczenia klienta w ["wstrzymany", "zawieszony", "zaległy"]:
    odrzucić(402, „Stan rozliczenia nie pozwala na użycie”)
jeśli żądany_model nie znajduje się w Customer.allowed_models:
    odrzucić(403, „Model nie jest włączony dla tego obszaru roboczego”)
jeśli bieżący_okres_wydatków + szacowany_maks.koszt > klient.hard_cap:
    odrzucić(402, „Przekroczono limit wydatków”)
jeśli limit_stawki_przekroczony(id_klienta, żądany_model):
    odrzucić(429, „Przekroczono limit szybkości”)
Route_request()

Fakt: 10 najważniejszych zabezpieczeń interfejsu API OWASP w 2023 r. jako główne zagrożenia API uznaje zepsutą autoryzację obiektów, zepsute uwierzytelnianie i nieograniczone zużycie zasobów. Odnoszą się one bezpośrednio do portali sprzedawców: jeden najemca nie może czytać danych innego najemcy, klucze nie mogą być omijane, a jeden klient nie może mieć możliwości tworzenia nieograniczonych wydatków dostawcy.

Kompromis: rygorystyczne, twarde limity chronią Twoją marżę, ale mogą przerwać uzasadnione skoki. Dobrym kompromisem jest tymczasowy przepływ pracy z datą wygaśnięcia, osobą zatwierdzającą, przyczyną i wpisem dziennika audytu.

Księga użytkowania jako źródło prawdy

Aby mieć kontrolę dostępu w czasie rzeczywistym, prowadź własną księgę użytkowania. Zewnętrzne narzędzia rozliczeniowe doskonale nadają się do fakturowania, ale zazwyczaj nie są właściwym miejscem do podejmowania decyzji o zezwoleniu lub odmowie na poziomie milisekund.

Zdarzenie użycia powinno rejestrować wystarczająco dużo szczegółów, aby uzgodnić faktury dostawcy, wyjaśnić rachunki klientów i rozwiązać spory:

{
  "request_id": "req_01J...",
  "idempotency_key": "idem_abc123",
  "partner_id": "partner_123",
  "customer_id": "customer_acme",
  "workspace_id": "ws_prod",
  "api_key_id": "key_live_789",
  "model": "standard rozumowania",
  „tokeny_wejściowe”: 1850,
  „tokeny_wyjściowe”: 420,
  „cached_tokens”: 1200,
  „koszt_dostawcy”: 0,0142,
  „cena_sprzedawcy”: 0,0230,
  "waluta": "USD",
  "znacznik czasu": "2026-08-02T10:15:30Z",
  „status”: „udało się”

Rejestruj także żądania zakończone niepowodzeniem, ale odróżniaj awarie podlegające rozliczeniu od niepowodzeń, które nie są płatne. Przekroczenia limitu czasu dostawcy, błędy weryfikacji, anulowanie przez klienta, ponowne próby i blokady bezpieczeństwa mogą mieć różne skutki rozliczeniowe w zależności od tego, kiedy wystąpią.

Zalecenie: zapisz oczekujące zdarzenie w księdze, gdy żądanie zostanie zaakceptowane, a następnie sfinalizuj je, gdy znane będzie użycie i koszt tokena. Dzięki temu możesz zarezerwować budżet przed skierowaniem, a następnie skorygować ostateczną kwotę po zakończeniu.

Wzorzec uzgadniania

1. Przechowuj zdarzenia na poziomie żądania w księdze wewnętrznej.
2. Zbiorcze wykorzystanie według klienta, modelu i okresu rozliczeniowego.
3. Porównaj wewnętrzne sumy z fakturami dostawców zewnętrznych lub eksportami wykorzystania.
4. Przed wystawieniem faktury sprawdź istotne różnice.
5. Synchronizuj podsumowanie płatnego wykorzystania z systemem rozliczeniowym.

Kompromis: synchronizacja podsumowanego użycia zmniejsza liczbę i złożoność zdarzeń rozliczeniowych, ale może sprawić, że faktury klientów będą mniej szczegółowe. Jeśli klienci potrzebują raportowania na poziomie modelu lub projektu, zachowaj te wymiary w synchronizacji rozliczeń lub w panelu klienta.

Synchronizacja rozliczeń z licznikami opartymi na wykorzystaniu

Systemy rozliczeń oparte na użyciu zazwyczaj działają zgodnie ze schematem: definiują produkty i ceny, przetwarzają zdarzenia dotyczące użycia, agregują je w okresie rozliczeniowym, generują faktury i monitorują błędy. Na przykład Stripe Billing obsługuje zdarzenia licznika z nazwą zdarzenia, identyfikatorem klienta, wartością liczbową, opcjonalnym znacznikiem czasu, opcjonalnym identyfikatorem idempotencji i opcjonalnymi wymiarami.

W przypadku rozliczeń za pomocą interfejsu API AI najczęściej wybierane liczniki to:

• Suma tokenów: przydatna, gdy ceny są ściśle powiązane z tokenami wejściowymi i wyjściowymi.
• Liczba żądań: przydatna w przypadku prostych planów lub wywołań API o niskim tokenie.
• Jednostki specyficzne dla modelu: przydatne, gdy modele premium mają różne marże.
• Siedziska lub aktywne obszary robocze: przydatne w hybrydowych planach SaaS plus użytkowanie.

Fakt: mierniki paskowe obsługują formuły agregacji, takie jak suma, liczba i ostatnia. Odwzorowują one sumy tokenów, liczbę żądań i wartości podobne do stanu, takie jak miejsca lub aktywne limity.

Codzienna synchronizacja rozliczeń może powodować powstawanie takich zdarzeń licznika:

{
  "event_name": "ai_tokens_used",
  "klient": "pasek_klient_456",
  „wartość”: 2270000,
  "znacznik czasu": "2026-08-02T23:59:00Z",
  "idempotency_key": "cust_acme_2026-08-02_tokens",
  „wymiary”: {
    "plan": "growth_api",
    "model_family": "standardowy"
  }

Zalecenie: prowadź księgę wewnętrzną bardziej szczegółową niż faktura. Możesz wystawiać faktury za dzienne sumy tokenów, zachowując jednocześnie zapisy na poziomie żądań dotyczące wsparcia, przeglądu oszustw, dostrajania limitów stawek i analizy marży.

Operacje na telegramie bez uczynienia Telegramu systemem rejestrującym

Telegram jest przydatny w szybkich przepływach pracy operatorów: zespoły pomocy technicznej już zauważają wiadomości, boty mogą wysyłać alerty, a klienci mogą otrzymywać instrukcje dotyczące wdrożenia bez konieczności logowania się do pulpitu nawigacyjnego. Ale Telegram nie powinien być jedyną ścieżką audytu przy podejmowaniu decyzji dotyczących rozliczeń, bezpieczeństwa lub wsparcia.

Dobre przepływy pracy w Telegramie obejmują:

• Alerty o niskim saldzie lub wysokich wydatkach przy 50%, 80% i 95% limitu.
• Wiadomości wprowadzające nowych klientów z linkami do dokumentacji i zamaskowanymi nazwami kluczy.
• Powiadomienia o rotacji kluczy API przed i po rotacji.
• Alerty dotyczące awarii dostawcy lub uszkodzonego modelu.
• Eskalacja pomocy technicznej, gdy klient napotka powtarzające się błędy 401, 402, 403 lub 429.

Fakt: Wywołania interfejsu API bota Telegramu są wykonywane za pośrednictwem protokołu HTTPS do punktów końcowych tokenu bota, a elementy webhook Telegram mogą zawierać nagłówek tajnego tokenu, aby pomóc zweryfikować pochodzenie elementu webhook.

Zalecenie: przechowuj identyfikatory czatu Telegramu jako metadane dzierżawy, ale nie udostępniaj ich klientom. Rejestruj każdą czynność administracyjną wywołaną przez bota w dzienniku audytu wewnętrznego, podając aktora, sygnaturę czasową, klienta, starą, nową wartość i przyczynę.

Lista kontrolna bezpieczeństwa i izolacji

Przed sprzedażą dostępu przetestuj izolację najemcy tak, jakby klient aktywnie próbował przekroczyć granice.

• Klient A nie może wyświetlić kluczy API Klienta B.
• Klient A nie może przeglądać wykorzystania Klienta B, faktur, limitów, identyfikatorów czatu Telegram ani stanu rozliczeń.
• Unieważniony klucz kończy się natychmiastowym niepowodzeniem na wszystkich ścieżkach żądań.
• Klient, którego płatności zostały wstrzymane, nie może kontynuować wydatków w ramach sesji w pamięci podręcznej ani starych kluczy.
• Klient nie może zamówić modeli spoza przypisanego planu.
• Limity stawek obowiązują w zależności od klienta i obszaru roboczego, a nie tylko globalnego adresu IP.
• Procedury obsługi webhook weryfikują podpisy lub tajne nagłówki, jeśli są obsługiwane.
• Wszystkie udostępnienia, zmiany limitów, rotacja kluczy i nadpisania płatności tworzą wpisy w dzienniku kontrolnym.
• Logika ponawiania używa kluczy idempotencji, więc zduplikowane żądania nie powodują podwójnego obciążania klientów.
• Narzędzia pomocy maskują tajemnice i ograniczają, kto może ujawniać lub zmieniać klucze.

Przewidywanie: portale sprzedawców będą w coraz większym stopniu konkurować w zakresie zarządzania i przejrzystości rozliczeń, a nie tylko dostępu do wielu modeli. Klienci będą oczekiwać wykorzystania poszczególnych projektów, przejrzystych faktur, szybkiej rotacji kluczy i kontroli wydatków w ramach standardowych funkcji.

Kluczowe kompromisy, które należy podjąć wcześnie

Przedpłata a płatność z dołu

Salda przedpłacone zmniejszają ryzyko kredytowe i ułatwiają ostateczne odcięcie spłaty, ale klienci mogą nie lubić przerw. Rozliczenia z dołu są łatwiejsze w przypadku stałych klientów, ale wymagają kontroli kredytowej, przepływów pracy z monitami i skuteczniejszego wykrywania anomalii.

Jedna cena mieszana w porównaniu z cenami dla konkretnego modelu

Łatwiej jest wyjaśnić cenę mieszaną. Ceny specyficzne dla modelu chronią marże i zachęcają do efektywnego wyboru modelu. Jeśli oferujesz wiele modeli, opublikuj prosty katalog modeli skierowany do klienta i ukryj niepotrzebną złożoność specyficzną dla dostawcy.

Pomiary w czasie rzeczywistym a rozliczenia z opóźnieniem

Pomiary w czasie rzeczywistym umożliwiają wykorzystanie limitów wydatków i sald przedpłaconych. Wymaga także trwałych zapisów, obsługi powtórek i uzgadniania. Opóźnione rozliczenia są prostsze, ale narażają Cię na niekontrolowane wydatki, zanim limity zaczną obowiązywać.

Wsparcie oparte przede wszystkim na telegramie a wsparcie na panelu sterowania

Telegram jest szybki i znajomy dla wielu operatorów. Pulpit nawigacyjny jest lepszy pod względem kontroli, eksportu, uprawnień i samoobsługi klienta. Używaj Telegramu do powiadomień i zatwierdzeń, ale przechowuj zapis kanoniczny w swoim systemie.

Przydatny plan wdrożenia

1. Zacznij od izolacji najemcy: zaimplementuj rekordy klientów, obszarów roboczych, kluczy, planów i limitów przed dodaniem zaawansowanych funkcji rozliczeniowych.
2. Wprowadź egzekwowanie zasad przed inspekcją: blokuj unieważnione klucze, zawieszone płatności, niedozwolone modele i przekraczaj limity ruchu przed routingiem.
3. Utwórz księgę użytkowania: rejestruj identyfikatory żądań, liczbę tokenów, koszty, ceny odsprzedawcy, statusy, znaczniki czasu i klucze idempotencji.
4. Dodaj uzgodnienie: przed wystawieniem faktury porównaj wykorzystanie wewnętrzne z sumą dostawców wyższego szczebla.
5. Synchronizuj podsumowania rozliczeń: wysyłaj dzienne lub godzinne dane zbiorcze na swoją platformę rozliczeniową ze stabilnymi mapowaniami klientów i kluczami idempotencji.
6. Alerty za pośrednictwem telegramu: rozpoczynają się od komunikatów o niskim saldzie, przestojach, rotacji kluczy i eskalacji pomocy.
7. Przeprowadź testy izolacyjne: sprawdź, czy żaden klient nie ma dostępu do kluczy, użycia, limitów, faktur ani metadanych czatu innego klienta.

Portal sprzedawcy to nie tylko opakowanie interfejsu API AI. Jest to warstwa operacyjna obejmująca uwierzytelnianie, zasady najemcy, analizę użycia, rozliczenia i pomoc techniczną. Najpierw utwórz księgę i limity, przechowuj klucze nadrzędne po stronie serwera i spraw, aby każdy klucz dostępny dla klienta był odwołalny, miał określony zakres i możliwość przypisania.

Powiązane lektury

• Izolacja kluczy API i praktyki rotacyjne
• Techniki kontroli kosztów interfejsu API AI
• routing i ponowne próby uwzględniające awarie