Construiți un portal de distribuitori AI API: furnizarea chiriașilor, măsurarea utilizării, facturarea și operațiunile Telegram

Dacă împachetați acces AI pentru clienți, nu le înmânați cheile furnizorului dvs. din amonte. Creați un nivel de reseller care emite chei la nivelul clientului, impune limitele locatarului înainte de fiecare solicitare, înregistrează utilizarea în propriul registru și sincronizează totalurile facturabile cu sistemul dvs. de facturare.

Acest ghid descrie un model de operare practic pentru un API AI pentru agenții, consultanți și constructori SaaS. Nu este un studiu de caz pentru clienți. Este o arhitectură de referință pe care o puteți adapta indiferent dacă utilizați un API Partner, un gateway intern sau un proxy personalizat în fața mai multor furnizori de modele.

Arhitectura portalului de reseller

Un portal de distribuitori sigur separă patru responsabilități:

• Administrarea partenerilor: aplicația dvs. internă pentru crearea de clienți, planuri, chei, limite și fluxuri de lucru de asistență.
• Aplicarea solicitărilor: calea gateway-ului care autentifică cheile clientului, verifică politica, direcționează solicitările și blochează traficul care depășește limitarea.
• Contabilitatea utilizării: un registru durabil care înregistrează utilizarea la nivel de solicitare și intrările privind prețurile.
• Facturare și operațiuni: sincronizare programată a facturilor, alerte, notificări de rotație a cheilor și escaladare a asistenței.

Un flux tipic arată astfel:

Aplicația de administrator al partenerilor
  → Partener API
    → înregistrările clienților/spațiului de lucru
    → chei API la nivelul clientului
    → plan, model, buget și limite de tarif
    → solicitați gateway
    → registru de utilizare
    → sincronizare facturare
    → Botul de notificare Telegram

Realitate: OpenAI recomandă să nu partajați cheile API bazate pe utilizatori pentru colaborare și, în schimb, să utilizați chei bazate pe proiecte, membri alocați și chei distincte cu limite de rate izolate și controale de cheltuieli. Termenii serviciilor OpenAI interzic, de asemenea, cumpărarea, vânzarea sau transferul cheilor API către sau de la o terță parte. Aceste fapte susțin un design de reseller în care acreditările din amonte rămân la nivelul serverului, iar clienții primesc propriile chei în aval.

Recomandare: emiteți o cheie în aval pentru fiecare client, proiect sau mediu. Nu reutilizați o cheie de client pe mai mulți clienți finali. Nu expuneți acreditările furnizorului din amonte în documentație, codul browserului, aplicațiile mobile, jurnalele sau mesajele de asistență pentru clienți.

Model de date pentru chiriași

Modelul chiriașului ar trebui să explice izolarea. Cel puțin, stocați aceste câmpuri:

partener_id
client_id
workspace_id
api_key_id
plan_id
starea_facturare
cheltuială_limită
rate_limit
modele_permise
telegram_chat_id
usage_ledger_id
creat_la
updated_at
revocat_at

Într-un portal mai mare, adăugați câmpuri pentru sold preplătit, monedă, regiune fiscală, ID-ul client al facturii, nivelul de asistență, starea abuzului și înlocuiri temporare.

Exemplu de înregistrare client

{
  "partner_id": "partner_123",
  "customer_id": "cust_acme",
  "workspace_id": "ws_prod",
  "plan_id": "growth_api",
  "billing_status": "activ",
  „send_limit”: {
    "perioada": "luna",
    "hard_cap_usd": 500,
    „alert_thresholds”: [0,5, 0,8, 0,95]
  },
  "rate_limit": {
    „cereri_per_minut”: 120,
    „tokens_per_day”: 2000000
  },
  "allowed_models": ["fast-chat", "raționament-standard"],
  "telegram_chat_id": "-1001234567890",
  "usage_ledger_id": "ledger_cust_acme"
}

Recomandare: tratați customer_id, workspace_id și api_key_id ca concepte separate. Un client poate avea mai multe spații de lucru și fiecare spațiu de lucru poate avea nevoie de chei separate de producție, punere în scenă și dezvoltare. Acest lucru face revocarea, depanarea și atribuirea utilizării mult mai ușoare.

Secvența de înscriere pentru un client nou

Un flux de onboarding fiabil este plictisitor prin design. Ar trebui să producă aceleași înregistrări de fiecare dată și să lase o urmă de audit.

1. Creați clientul: stocați numele legal, contactul de facturare, contactul tehnic și proprietarul intern.
2. Creați un spațiu de lucru: separați producția de testare dacă clientul se va integra programatic.
3. Atribuiți un plan: definiți modelele incluse, marcajul, cadența de facturare și așteptările de asistență.
4. Setați limite: configurați limite de cheltuieli, limite de solicitare, limite de simboluri și politica de explozie.
5. Creați chei API: emiteți chei definite pentru mediile clientului.
6. Trimiteți instrucțiuni de integrare: furnizați adresa URL de bază, formatul de autentificare, lista de modele, limitele și canalul de asistență.
7. Activați alertele: conectați Telegram sau alt canal de operațiuni pentru notificări de sold scăzut, cheie, întrerupere și facturare.
8. Executați o solicitare de testare: verificați autentificarea, înregistrarea utilizării, accesul la model și maparea facturilor.

Recomandare: faceți integrarea idempotentă. Dacă aplicația dvs. de administrare reîncearcă o operațiune de „creare client”, nu ar trebui să creeze înregistrări de facturare duplicate sau chei API duplicate. Folosiți ID-uri externe și chei de idempotenta pentru furnizarea apelurilor.

Controlul bugetului la momentul solicitării

Cea mai importantă aplicare are loc înainte ca cererea să ajungă la un model din amonte. Gateway-ul dvs. nu ar trebui să descopere că un client depășește bugetul numai după ce furnizorul v-a taxat deja.

Utilizați această secvență de verificare prealabilă:

1. Autentificați cheia API din aval.
2. Rezolvați partner_id, customer_id și workspace_id.
3. Verificați dacă cheia este activă și nu este revocată.
4. Verificați starea facturării: activ, în curs de încercare, plătit anticipat, întrerupt, întârziat sau suspendat.
5. Verificați limita de cheltuieli pentru perioada curentă de facturare.
6. Verificați limitele ratelor, cum ar fi solicitările pe minut și jetoanele pe zi.
7. Verificați dacă modelul solicitat este permis pentru planul clientului.
8. Estimați costul maxim posibil din model, jetoane maxime și parametrii de solicitare.
9. Dirijați solicitarea numai dacă politica este aprobată.

dacă key.revoked:
    reject(401, „Cheia API revocată”)
dacă customer.billing_status în ["paused", "suspended", "overdee"]:
    respinge(402, „Starea de facturare nu permite utilizarea”)
dacă requested_model nu este în customer.allowed_models:
    reject(403, „Modelul nu este activat pentru acest spațiu de lucru”)
dacă current_period_spend + estimated_max_cost > customer.hard_cap:
    respinge(402, „Limita de cheltuieli depășită”)
dacă rate_limit_exceeded(customer_id, requested_model):
    respinge(429, „Limita ratei depășită”)
route_request()

Realitate: OWASP API Security Top 10 2023 indică drept riscuri majore API autorizarea obiectelor deteriorate, autentificarea întreruptă și consumul nerestricționat de resurse. Acestea se mapează direct la portalurile de distribuitori: un chiriaș nu trebuie să citească datele altui chiriaș, cheile nu trebuie să fie ocolite și un client nu trebuie să poată crea cheltuieli nelimitate ale furnizorului.

Compartiment: limitele stricte vă protejează marja, dar pot întrerupe creșterile legitime. Un compromis bun este un flux de lucru de anulare temporară, cu o dată de expirare, un aprobator, un motiv și o intrare în jurnalul de audit.

Folosește registrul ca sursă a adevărului

Pentru controlul accesului în timp real, păstrați propriul registru de utilizare. Instrumentele externe de facturare sunt excelente pentru facturare, dar de obicei nu sunt locul potrivit pentru a lua decizii de autorizare sau refuzare la nivel de milisecunde.

Un eveniment de utilizare ar trebui să cuprindă suficiente detalii pentru a reconcilia facturile furnizorilor, pentru a explica facturile clienților și pentru a remedia disputele:

{
  "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": "raționament-standard",
  „input_tokens”: 1850,
  „output_tokens”: 420,
  „cached_tokens”: 1200,
  „cost_furnizor”: 0,0142,
  „preț_reseller”: 0,0230,
  "currency": "USD",
  "timestamp": "2026-08-02T10:15:30Z",
  "status": "reușit"
}

Înregistrați și cererile eșuate, dar distingeți eșecurile care sunt facturabile de eșecurile care nu sunt. Limitările de timp ale furnizorului, eșecurile de validare, anulările clienților, reîncercările și blocările de siguranță pot avea rezultate contabile diferite, în funcție de momentul în care apar.

Recomandare: scrieți un eveniment în registru în așteptare când cererea este acceptată, apoi finalizați-l când se cunoaște utilizarea simbolului și costul. Acest lucru vă permite să rezervați bugetul înainte de rutare și apoi să corectați suma finală după finalizare.

Model de reconciliere

1. Stochează evenimente la nivel de solicitare în registrul contabil intern.
2. Utilizarea agregată în funcție de client, model și perioada de facturare.
3. Comparați totalurile interne cu facturile furnizorilor din amonte sau cu exporturile de utilizare.
4. Investigați diferențele semnificative înainte de a emite facturi.
5. Sincronizați utilizarea facturabilă rezumată cu sistemul de facturare.

Compartiment: sincronizarea utilizării rezumate reduce volumul și complexitatea evenimentelor de facturare, dar poate face ca facturile clienților să fie mai puțin detaliate. Dacă clienții au nevoie de raportare la nivel de model sau la nivel de proiect, păstrați acești parametri în sincronizarea facturării sau în tabloul de bord pentru clienți.

Sincronizarea facturării cu contoare bazate pe utilizare

Sistemele de facturare bazate pe utilizare urmează, în general, un model: definiți produsele și prețurile, asimilați evenimentele de utilizare, le agregați pe o perioadă de facturare, generați facturi și monitorizați erorile. Stripe Billing, de exemplu, acceptă evenimente de contor cu un nume de eveniment, un identificator de client, o valoare numerică, un marcaj temporal opțional, un identificator opțional de idempotitate și dimensiuni opționale.

Pentru facturarea AI API, opțiunile comune ale contorului sunt:

• Token total: util atunci când prețul este strâns legat de indicativele de intrare și de ieșire.
• Număr de solicitări: util pentru planuri simple sau apeluri API cu simboluri reduse.
• Unități specifice modelului: util atunci când modelele premium au marje diferite.
• Locuri sau spații de lucru active: utile pentru planurile hibride de utilizare SaaS-plus.

Realitate: contoarele de bandă acceptă formule de agregare precum suma, numărul și ultimul. Acestea sunt asociate cu totalurile indicative, numărul de solicitări și valori asemănătoare stării, cum ar fi locurile sau limitele active.

O sincronizare zilnică a facturării poate crea evenimente de contor precum acesta:

{
  "event_name": "ai_tokens_used",
  "client": "stripe_customer_456",
  „valoare”: 2270000,
  „stamp”: „2026-08-02T23:59:00Z”,
  "idempotency_key": "cust_acme_2026-08-02_tokens",
  "dimensiuni": {
    "plan": "growth_api",
    "model_family": "standard"
  }
}

Recomandare: păstrați registrul intern mai detaliat decât factura. Puteți factura totalurile zilnice de simboluri, păstrând în același timp înregistrările la nivel de solicitare pentru asistență, examinarea fraudelor, ajustarea limitelor ratelor și analiza marjelor.

Operațiunile Telegram fără a face din Telegram sistemul de înregistrare

Telegram este util pentru fluxurile de lucru rapide ale operatorilor: echipele de asistență observă deja mesaje, roboții pot trimite alerte, iar clienții pot primi instrucțiuni de integrare fără a se conecta la un tablou de bord. Dar Telegram nu ar trebui să fie singura pistă de audit pentru deciziile de facturare, securitate sau asistență.

Fluxurile de lucru bune Telegram includ:

• Alerte privind soldul scăzut sau cheltuiala mare la 50%, 80% și 95% dintr-un plafon.
• Mesaje noi de înscriere a clienților cu linkuri de documentație și nume de chei mascate.
• Notări de rotație a cheilor API înainte și după rotație.
• Alerte de întrerupere a furnizorului sau de modele degradate.
• Escalarea asistenței umane atunci când un client lovește erori repetate 401, 402, 403 sau 429.

Realitate: apelurile Telegram Bot API sunt efectuate prin HTTPS către punctele finale cu simbol bot, iar webhook-urile Telegram pot include un antet secret pentru simbol pentru a ajuta la verificarea originii webhook.

Recomandare: stocați ID-urile de chat Telegram ca metadate ale chiriașilor, dar nu le expuneți clienților. Înregistrați fiecare acțiune administrativă declanșată de bot în jurnalul dvs. de audit intern cu actor, marca temporală, client, valoare veche, valoare nouă și motiv.

Lista de verificare pentru securitate și izolare

Înainte de a vinde acces, testați izolarea chiriașilor ca și cum un client încearcă în mod activ să depășească granițele.

• Clientul A nu poate vedea cheile API pentru Clientul B.
• Clientul A nu poate vedea utilizarea clientului B, facturile, limitele, ID-urile de chat Telegram sau starea de facturare.
• O cheie revocată eșuează imediat pe toate căile de solicitare.
• Un client întrerupt de facturare nu poate continua să cheltuiască prin sesiuni memorate în cache sau prin chei vechi.
• Un client nu poate solicita modele în afara planului alocat.
• Limitele tarifelor se aplică în funcție de client și spațiul de lucru, nu numai după adresa IP globală.
• Managerii webhook verifică semnăturile sau anteturile secrete acolo unde sunt acceptate.
• Toate aprovizionarea, modificările limitelor, rotațiile cheilor și înlocuirile de facturare creează intrări în jurnalul de audit.
• Logica de reîncercare folosește chei de idempotenta, astfel încât cererile duplicate nu fac dublu factura clienților.
• Instrumentele de asistență maschează secretele și limitează cine poate dezvălui sau roti cheile.

Predicție: portalurile de distribuitori vor concura din ce în ce mai mult în ceea ce privește guvernanța și claritatea facturării, nu doar accesul la multe modele. Clienții se vor aștepta ca funcții standard la utilizarea pe fiecare proiect, facturi clare, rotație rapidă a tastelor și controale de cheltuieli grele.

Compartimente cheie pentru a decide din timp

Plătit anticipat versus plătit ulterioară

Soldurile plătite în avans reduc riscul de credit și simplifică întreruperile dure, dar clienților le pot dispărea întreruperile. Facturarea cu plată ulterioară este mai simplă pentru clienții consacrați, dar necesită verificări de credit, fluxuri de lucru de solicitare și o detectare mai puternică a anomaliilor.

Un preț combinat față de prețul specific modelului

Un preț combinat este mai ușor de explicat. Prețurile specifice modelului protejează marjele și încurajează selecția eficientă a modelului. Dacă oferiți multe modele, publicați un catalog de modele simplu orientat către clienți și ascundeți complexitatea inutilă specifică furnizorului.

Contorizare în timp real versus facturare întârziată

Contorizarea în timp real permite limite de cheltuieli și solduri preplătite. De asemenea, necesită scrieri durabile, gestionarea reluării și reconciliere. Facturarea întârziată este mai simplă, dar vă expune la cheltuieli fulminante înainte ca limitele să intre în vigoare.

Asistență în primul rând Telegram versus asistență în primul rând pe tabloul de bord

Telegram este rapid și familiar pentru mulți operatori. Un tablou de bord este mai bun pentru auditabilitate, exporturi, permisiuni și autoservire pentru clienți. Utilizați Telegram pentru notificări și aprobări, dar stocați înregistrarea canonică în sistemul dvs.

Plan de lansare acționabil

1. Începeți cu izolarea chiriașilor: implementați înregistrările client, spațiu de lucru, cheie, plan și limitați înainte de a adăuga funcții avansate de facturare.
2. Creați aplicarea preflight: blocați cheile revocate, suspendarea facturării, modelele interzise și depășiți traficul înainte de rutare.
3. Creați registrul de utilizare: înregistrați ID-urile solicitărilor, numărul de simboluri, costurile, prețurile revânzătorului, stările, marcajele de timp și cheile de idempotitate.
4. Adăugați o reconciliere: comparați utilizarea internă cu totalul furnizorilor din amonte înainte de facturare.
5. Sincronizați rezumatele facturării: trimiteți agregate zilnice sau orare către platforma dvs. de facturare cu mapări stabile ale clienților și chei de idempotenta.
6. Alerte Telegram prin cablu: începe cu mesaje de echilibru scăzut, întreruperi, rotație a tastelor și mesaje de escaladare a suportului.
7. Efectuați teste de izolare: verificați dacă niciun client nu poate accesa cheile, utilizarea, limitele, facturile sau metadatele de chat ale altui client.

Un portal de reseller nu este doar un înveliș în jurul unui API AI. Este un nivel de operare pentru autentificare, politica chiriașilor, analiza utilizării, facturare și asistență. Creați mai întâi registrul și limitele, păstrați cheile din amonte pe partea serverului și faceți ca fiecare cheie orientată către client să fie revocabilă, acoperită și atribuibilă.

Lectură similară

• Tehnici de control al costurilor API AI
• routare și reîncercări care țin cont de eșecuri