Vybudujte si AI API Reseller Portal: Provisioning tenant, měření využití, fakturace a operace telegramu

Pokud klientům zabalíte přístup AI, nepředávejte jim klíče od poskytovatele upstreamu. Vytvořte vrstvu distributora, která vydává klíče v rozsahu zákazníka, vynucuje limity nájemců před každým požadavkem, zaznamenává využití do vaší vlastní účetní knihy a synchronizuje fakturovatelné součty do vašeho fakturačního systému.

Tato příručka popisuje praktický provozní model pro AI API pro agentury, konzultanty a tvůrce SaaS. Nejedná se o případovou studii zákazníka. Jde o referenční architekturu, kterou můžete přizpůsobit, ať už používáte Partner API, interní bránu nebo vlastní proxy před více poskytovateli modelů.

Architektura portálu distributora

Bezpečný portál distributora odděluje čtyři odpovědnosti:

• Administrace partnerů: vaše interní aplikace pro vytváření zákazníků, plánů, klíčů, limitů a pracovních postupů podpory.
• Vynucení požadavků: cesta brány, která ověřuje zákaznické klíče, kontroluje zásady, směruje požadavky a blokuje nadlimitní provoz.
• Účtování využití: odolná účetní kniha, která zaznamenává využití na úrovni požadavků a cenové vstupy.
• Fakturace a operace: plánovaná synchronizace faktur, upozornění, upozornění na střídání klíčů a eskalace podpory.

Typický postup vypadá takto:

Administrátorská aplikace pro partnery
  → Partner API
    → evidence zákazníků / pracovních prostorů
    → Klíče API přizpůsobené zákazníkovi
    → plán, model, rozpočet a limity sazeb
    → brána požadavku
    → kniha použití
    → synchronizace fakturace
    → Robot pro upozornění na telegram

Fakt: OpenAI doporučuje nesdílet uživatelské klíče API pro spolupráci a místo toho používat klíče založené na projektu, přiřazené členy a odlišné klíče s izolovanými limity sazeb a kontrolami výdajů. Podmínky služeb OpenAI také zakazují nákup, prodej nebo převod API klíčů na nebo od třetí strany. Tato fakta podporují návrh prodejce, kde přihlašovací údaje pro upstream zůstávají na straně serveru a zákazníci dostávají vaše vlastní downstream klíče.

Doporučení: Vydejte jeden následný klíč pro každého zákazníka, projekt nebo prostředí. Nepoužívejte opakovaně jeden zákaznický klíč pro více koncových klientů. Nezveřejňujte přihlašovací údaje poskytovatele upstream v dokumentaci, kódu prohlížeče, mobilních aplikacích, protokolech nebo zprávách podpory klientů.

Datový model nájemce

V modelu tenanta by měla být izolace explicitní. Uložte minimálně tato pole:

id_partnera
customer_id
workspace_id
api_key_id
plan_id
fakturační_stav
výdajový_limit
sazba_limit
povolené_modely
telegram_chat_id
use_ledger_id
created_at
updated_at
revoked_at

Ve větším portálu přidejte pole pro předplacený zůstatek, měnu, daňový region, číslo zákazníka faktury, úroveň podpory, stav zneužití a dočasné přepsání.

Příklad záznamu zákazníka

{
  "partner_id": "partner_123",
  "customer_id": "cust_acme",
  "workspace_id": "ws_prod",
  "plan_id": "growth_api",
  "billing_status": "aktivní",
  "spend_limit": {
    "period": "měsíc",
    "hard_cap_usd": 500,
    "alert_thresholds": [0,5; 0,8; 0,95]
  },
  "rate_limit": {
    "požadavky_za_minutu": 120,
    "tokens_per_day": 2000000
  },
  "allowed_models": ["fast-chat", "reasoning-standard"],
  "telegram_chat_id": "-1001234567890",
  "usage_ledger_id": "ledger_cust_acme"
}

Doporučení: pokládejte customer_id, workspace_id a api_key_id za samostatné pojmy. Zákazník může mít více pracovních prostorů a každý pracovní prostor může potřebovat samostatné produkční, pracovní a vývojové klíče. Díky tomu je odvolání, ladění a přiřazení použití mnohem jednodušší.

Sekvence registrace pro nového zákazníka

Spolehlivý proces registrace je nudný. Pokaždé by měl vytvořit stejné záznamy a zanechat auditní stopu.

1. Vytvoření zákazníka: obchodní jméno, fakturační kontakt, technický kontakt a interní vlastník.
2. Vytvořte pracovní prostor: oddělte produkci od testování, pokud se zákazník bude integrovat programově.
3. Přiřazení plánu: definujte zahrnuté modely, označení, kadenci fakturace a očekávání podpory.
4. Nastavte limity: nakonfigurujte limity útraty, limity požadavků, limity tokenů a zásady shluků.
5. Vytvořte klíče API: Vydávejte klíče s rozsahem pro prostředí zákazníka.
6. Odešlete pokyny k integraci: uveďte základní adresu URL, formát ověření, seznam modelů, limity a kanál podpory.
7. Povolit upozornění: připojte Telegram nebo jiný provozní kanál pro upozornění na nízký zůstatek, klíč, výpadek a fakturaci.
8. Spusťte testovací požadavek: ověřte ověření, záznam využití, přístup k modelu a mapování faktur.

Doporučení: udělejte registraci idempotentní. Pokud se vaše aplikace pro správu znovu pokusí o operaci „vytvoření zákazníka“, neměla by vytvářet duplicitní fakturační záznamy ani duplicitní klíče API. Pro zajišťování hovorů používejte externí ID a klíče idempotence.

Kontrola rozpočtu v době požadavku

K nejdůležitějšímu vynucení dochází předtím, než požadavek dosáhne upstream modelu. Vaše brána by neměla zjistit, že zákazník překročil rozpočet až poté, co vám poskytovatel již naúčtoval poplatky.

Použijte tuto sekvenci před výstupem:

1. Ověřte downstream klíč API.
2. Vyřešte partner_id, customer_id a workspace_id.
3. Zkontrolujte, zda je klíč aktivní a není odvolán.
4. Zkontrolujte stav fakturace: aktivní, zkušební, předplacené, pozastavené, po splatnosti nebo pozastavené.
5. Zkontrolujte pevný limit útraty pro aktuální fakturační období.
6. Zkontrolujte limity četnosti, jako jsou požadavky za minutu a tokeny za den.
7. Zkontrolujte, zda je požadovaný model pro tarif zákazníka povolen.
8. Odhadněte maximální možné náklady z modelu, maximálního počtu tokenů a parametrů požadavku.
9. Směrovat požadavek pouze v případě, že zásady projdou.

if key.revoked:
    odmítnout(401, "klíč API odvolán")
pokud customer.billing_status v ["pozastaveno", "pozastaveno", "po splatnosti"]:
    odmítnout(402, "Stav fakturace neumožňuje použití")
pokud požadovaný_model není v customer.allowed_models:
    odmítnout(403, "Model není pro tento pracovní prostor povolen")
if current_period_spend + odhadované_maximální_náklady > customer.hard_cap:
    odmítnout(402, "překročen limit útraty")
if rate_limit_exceeded(customer_id, required_model):
    odmítnout(429, "překročen limit rychlosti")
route_request()

Fakt: Top 10 zabezpečení API OWASP 2023 označuje nefunkční autorizaci objektů, nefunkční ověřování a neomezenou spotřebu zdrojů jako hlavní rizika API. Ty se mapují přímo na portály prodejců: jeden tenant nesmí číst data jiného tenanta, klíče nesmí být obejít a jeden zákazník nesmí mít možnost vytvářet neomezené výdaje poskytovatele.

Trade-off: přísná pevná omezení chrání vaši marži, ale mohou přerušit legitimní nárůsty. Dobrým kompromisem je dočasné přepsání pracovního postupu s časem vypršení platnosti, schvalovatelem, důvodem a záznamem protokolu auditu.

Účetní kniha použití jako zdroj pravdy

Pro kontrolu přístupu v reálném čase si veďte vlastní účetní knihu použití. Externí fakturační nástroje jsou vynikající pro fakturaci, ale obvykle nejsou tím správným místem pro rozhodování o povolení nebo zamítnutí na úrovni milisekund.

Událost použití by měla zachycovat dostatek podrobností, aby bylo možné odsouhlasit faktury poskytovatele, vysvětlit účty zákazníků a ladit spory:

{
  "request_id": "req_01J...",
  "idempotency_key": "idem_abc123",
  "partner_id": "partner_123",
  "customer_id": "cust_acme",
  "workspace_id": "ws_prod",
  "api_key_id": "key_live_789",
  "model": "standardní uvažování",
  "input_tokens": 1850,
  "output_tokens": 420,
  "cached_tokens": 1200,
  "náklady_poskytovatele": 0,0142,
  "reseller_price": 0,0230,
  "currency": "USD",
  "timestamp": "2026-08-02T10:15:30Z",
  "status": "úspěšné"
}

Zaznamenávejte také neúspěšné požadavky, ale rozlišujte selhání, která jsou fakturovatelná, od selhání, která nejsou. Časové limity poskytovatele, selhání ověření, zrušení zákazníkem, opakované pokusy a bezpečnostní blokování mohou mít různé účetní výsledky v závislosti na tom, kdy k nim dojde.

Doporučení: po přijetí požadavku zapište nevyřízenou událost hlavní knihy a poté ji dokončete, až bude známo využití tokenu a cena. To vám umožní rezervovat rozpočet před směrováním a poté po dokončení opravit konečnou částku.

Vzor odsouhlasení

1. Ukládat události na úrovni požadavku do interní knihy.
2. Souhrnné využití podle zákazníka, modelu a fakturačního období.
3. Porovnejte interní součty s fakturami od poskytovatele nebo exporty využití.
4. Před vystavením faktur prozkoumejte podstatné rozdíly.
5. Synchronizujte souhrnné fakturovatelné využití s fakturačním systémem.

Výměna: synchronizace souhrnného využití snižuje objem a složitost fakturačních událostí, ale může způsobit, že faktury zákazníků budou méně podrobné. Pokud zákazníci potřebují vytváření přehledů na úrovni modelu nebo projektu, zachovejte tyto dimenze v synchronizaci fakturace nebo na zákaznickém panelu.

Synchronizace fakturace s měřiči podle využití

Fakturační systémy založené na použití se obecně řídí vzorem: definují produkty a ceny, zpracovávají události použití, agregují je za fakturační období, generují faktury a sledují chyby. Stripe Billing například podporuje události měřiče s názvem události, identifikátorem zákazníka, číselnou hodnotou, volitelným časovým razítkem, volitelným identifikátorem idempotency a volitelnými rozměry.

Pro fakturaci AI API jsou běžné možnosti měřiče:

• Celkový počet tokenů: užitečné, když je cena úzce svázána se vstupními a výstupními tokeny.
• Počet požadavků: užitečné pro jednoduché plány nebo volání rozhraní API s nízkým počtem tokenů.
• Jednotky specifické pro model: užitečné, když mají prémiové modely různé marže.
• Sedadla nebo aktivní pracovní prostory: užitečné pro hybridní plány využití SaaS plus.

Fakt: Měřiče pruhů podporují agregační vzorce, jako je součet, počet a poslední. Ty se mapují na součty tokenů, počty požadavků a hodnoty podobné stavu, jako jsou sedadla nebo aktivní limity.

Denní synchronizace fakturace může způsobit události měřiče, jako je tato:

{
  "event_name": "ai_tokens_used",
  "customer": "stripe_customer_456",
  "value": 2270000,
  "timestamp": "2026-08-02T23:59:00Z",
  "idempotency_key": "cust_acme_2026-08-02_tokens",
  "dimenze": {
    "plan": "growth_api",
    "model_family": "standardní"
  }
}

Doporučení: Udržujte interní účetní knihu podrobnější než fakturu. Můžete fakturovat denní součty tokenů a přitom si zachovat záznamy na úrovni požadavků pro podporu, kontrolu podvodů, ladění limitů sazeb a analýzu marže.

Operace telegramu, aniž by se telegram stal systémem záznamu

Telegram je užitečný pro rychlé pracovní postupy operátora: týmy podpory si již všimnou zpráv, roboti mohou posílat upozornění a zákazníci mohou dostávat pokyny pro vstup, aniž by se museli přihlašovat do řídicího panelu. Telegram by však neměl být jediným auditním záznamem pro rozhodnutí o účtování, zabezpečení nebo podpoře.

Dobré pracovní postupy telegramu zahrnují:

• Upozornění na nízký zůstatek nebo vysokou útratu při 50 %, 80 % a 95 % limitu.
• Nové zprávy o registraci zákazníků s odkazy na dokumentaci a maskovanými názvy klíčů.
• Oznámení o rotaci klíče API před a po rotaci.
• Upozornění na výpadek poskytovatele nebo zhoršený model.
• Eskalace lidské podpory, když zákazník opakovaně narazí na chyby 401, 402, 403 nebo 429.

Fakt: Volání rozhraní Telegram Bot API se uskutečňují přes HTTPS do koncových bodů bot-tokenů a webhooky Telegram mohou obsahovat hlavičku tajného tokenu, která pomáhá ověřit původ webhooku.

Doporučení: ukládejte ID chatu telegramu jako metadata nájemců, ale nevystavujte je mezi zákazníky. Zaznamenejte každou administrativní akci spuštěnou robotem do protokolu interního auditu s aktérem, časovým razítkem, zákazníkem, starou hodnotou, novou hodnotou a důvodem.

Kontrolní seznam zabezpečení a izolace

Před prodejem přístupu otestujte izolaci tenanta, jako by se zákazník aktivně snažil překročit hranice.

• Zákazník A nemůže zobrazit klíče API zákazníka B.
• Zákazník A nemůže zobrazit využití zákazníka B, faktury, limity, ID chatu v telegramu ani stav fakturace.
• Odvolaný klíč okamžitě selže na všech cestách požadavků.
• Zákazník s pozastavenou fakturací nemůže pokračovat v útratě prostřednictvím relací uložených v mezipaměti nebo starých klíčů.
• Zákazník nemůže požadovat modely mimo přidělený plán.
• Limity sazeb se vztahují na zákazníka a pracovní prostor, nejen na globální IP adresu.
• Obslužné nástroje webhooku ověřují podpisy nebo tajná záhlaví, pokud jsou podporovány.
• Všechno zajišťování, změny limitů, střídání klíčů a přepisy fakturace vytvářejí záznamy protokolu auditu.
• Logika opakování používá klíče idempotence, takže duplicitní požadavky zákazníkům neúčtují dvakrát.
• Podpůrné nástroje maskují tajemství a omezují, kdo může odhalit nebo otočit klíče.

Předpověď: Portály prodejců si budou stále více konkurovat v oblasti správy a přehlednosti fakturace, nejen v přístupu k mnoha modelům. Zákazníci budou jako standardní funkce očekávat využití pro jednotlivé projekty, jasné faktury, rychlé střídání klíčů a pevné kontroly výdajů.

Klíčové kompromisy pro včasné rozhodnutí

Předplacené versus následné platby

Předplacené zůstatky snižují úvěrové riziko a usnadňují tvrdá omezení, ale zákazníci nemusí mít rádi přerušení. Následná fakturace je pro zavedené zákazníky plynulejší, ale vyžaduje kontrolu kreditu, upomínací pracovní postupy a silnější detekci anomálií.

Jedna kombinovaná cena versus cena za konkrétní model

Smíšená cena se vysvětluje snadněji. Ceny specifické pro model chrání marže a podporují efektivní výběr modelu. Pokud nabízíte mnoho modelů, publikujte jednoduchý katalog modelů pro zákazníky a skryjte zbytečnou složitost specifickou pro poskytovatele.

Měření v reálném čase versus zpožděná fakturace

Měření v reálném čase umožňuje omezení útraty a předplacené zůstatky. Vyžaduje také trvalé zápisy, manipulaci s přehráváním a usmíření. Zpožděná fakturace je jednodušší, ale vystavuje vás útratě, než se limity projeví.

Telegram-first first versus dashboard-first support

Telegram je rychlý a známý mnoha operátorům. Řídicí panel je lepší pro auditovatelnost, exporty, oprávnění a zákaznickou samoobsluhu. Používejte telegram pro oznámení a schvalování, ale ukládejte kanonický záznam ve svém systému.

Akční plán zavedení

1. Začněte s izolací tenanta: implementujte záznamy o zákaznících, pracovních prostorech, klíčích, plánech a limitech před přidáním pokročilých funkcí fakturace.
2. Sestavte vynucení kontroly před výstupem: před směrováním zablokujte odvolané klíče, pozastavenou fakturaci, nepovolené modely a překročení limitu provozu.
3. Vytvořte knihu použití: zaznamenejte ID požadavků, počty tokenů, náklady, ceny prodejců, stavy, časová razítka a klíče idempotence.
4. Přidat odsouhlasení: před fakturací porovnejte interní využití s celkovými hodnotami u poskytovatele.
5. Synchronizace souhrnů fakturace: posílejte denní nebo hodinové souhrny do vaší fakturační platformy se stabilními mapováními zákazníků a klíči idempotence.
6. Upozornění prostřednictvím telegramu: začněte zprávami o nízkém zůstatku, výpadku, rotaci klíčů a eskalaci podpory.
7. Spusťte testy izolace: ověřte, že žádný zákazník nemá přístup ke klíčům, využití, limitům, fakturám nebo metadatům chatu jiného zákazníka.

Resellerský portál není jen obal kolem AI API. Jedná se o provozní vrstvu pro ověřování, zásady pro nájemce, analýzu využití, fakturaci a podporu. Nejprve sestavte účetní knihu a limity, ponechte upstream klíče na straně serveru a udělejte každý klíč pro zákazníky odvolatelný, s rozsahem a přiřaditelným.

Související informace

• postupy izolace a rotace
• Techniky řízení nákladů AI API
• směrování s ohledem na selhání a opakování