Fiecare cerere către API-ul Telm este autentificată cu o cheie API care începe cu tk_live_ — niciodată cu autentificarea din tabloul de bord. Creați o cheie în contul dumneavoastră, trimiteți-o în antetul Authorization ca token Bearer și ea acționează în numele contului dumneavoastră pe grupurile unde sunteți administrator. Dacă o cheie se scurge, revocați-o în tabloul de bord și emiteți una nouă.
1Cum funcționează cheile API
API-ul REST Telm nu folosește sesiunea browserului dumneavoastră. În schimb, fiecare cerere poartă o cheie API — un șir secret lung care începe cu prefixul tk_live_ urmat de caractere aleatorii. Cheia identifică contul dumneavoastră și autorizează apelul.
Generați chei din contul dumneavoastră și puteți deține mai multe simultan (de exemplu, câte una per script sau serviciu). Secretul complet este afișat o singură dată, la momentul creării; ulterior tabloul de bord listează o cheie după prefixul ei scurt (tk_live_ plus primele caractere) astfel încât să o puteți recunoaște, iar valoarea completă nu este niciodată păstrată după aceea.
- O cheie arată ca tk_live_ urmat de un șir aleatoriu lung.
- Cheile sunt create și gestionate în tabloul de bord.
- Secretul complet este afișat o singură dată — copiați-l imediat și păstrați-l undeva în siguranță.
- Tratați o cheie ca pe o parolă: oricine o are poate apela API-ul în numele dumneavoastră.
2Trimiterea cheii cu fiecare cerere
Trimiteți cheia în antetul Authorization folosind schema Bearer. Valoarea antetului este cuvântul Bearer, un spațiu și apoi cheia dumneavoastră — de exemplu, Authorization: Bearer tk_live_your_key_here.
Pentru clienții care nu pot seta comod un antet Authorization, API-ul acceptă cheia și într-un antet X-API-Key. Dacă ambele sunt prezente, câștigă antetul Authorization. Cererile prin orice altceva decât HTTPS nu sunt acceptate în producție.
- Preferat: trimiteți Authorization: Bearer tk_live_...
- Alternativă: trimiteți cheia în antetul X-API-Key în schimb.
- URL-ul de bază pentru fiecare apel este api.telm.com/api/public/v1.
- Consultați lista completă de endpoint-uri și schemele pe pagina pentru dezvoltatori.
3La ce poate accesa o cheie
O cheie acționează strict în numele contului dumneavoastră. Poate citi sau modifica doar grupuri unde contul dumneavoastră este administrator — o cerere care vizează orice alt grup returnează 404, astfel încât API-ul nu dezvăluie niciodată că un grup pe care nu îl puteți administra există măcar.
Accesul depinde și de planul grupului vizat. Endpoint-ul de verificare a spamului este deschis fiecărui plan în limita cotei zilnice, în timp ce API-ul complet (reguli, setări, listă albă, jurnal, analize, verificări în lot și webhook-uri) este disponibil pe planul Pro sau superior pe grupul implicat.
- O cheie poate atinge doar grupuri unde sunteți administrator.
- Cererile către grupuri pe care nu le administrați returnează 404, nu 403.
- Cota zilnică este partajată între toate cheile dumneavoastră, numărată per cont.
4Revocarea și rotirea cheilor
Dacă o cheie este expusă — încărcată într-un depozit, lipită într-un chat sau scursă în orice alt mod — revocați-o imediat din tabloul de bord. Revocarea intră în vigoare imediat: cheia revocată încetează să funcționeze în câteva secunde, nu după vreo întârziere.
Deoarece cota zilnică este partajată per cont, revocarea unei chei nu vă resetează contorul de utilizare. Rotirea regulată a cheilor este o bună igienă: creați cheia nouă, implementați-o în serviciul dumneavoastră, confirmați că funcționează, apoi revocați-o pe cea veche astfel încât să nu existe timp de nefuncționare.
- Revocați o cheie din tabloul de bord; încetează să funcționeze aproape imediat.
- Creați mai întâi înlocuitorul, lansați-l, apoi revocați cheia veche pentru o rotire fără timp de nefuncționare.
- Revocarea unei chei nu vă resetează cota zilnică — aceasta se resetează la miezul nopții UTC.
5Erori de autentificare
O cheie lipsă, malformată sau revocată returnează 401 cu un cod de eroare interpretabil de mașină și un mesaj lizibil pentru om. Dacă cererile dumneavoastră încep brusc să eșueze cu 401, verificați că cheia nu a fost revocată și că antetul Authorization este scris exact ca Bearer plus un spațiu plus cheia.
O cheie validă care vizează un grup pe care nu îl administrați returnează 404. O cheie validă pe un plan sub Pro care apelează un endpoint doar-Pro returnează 403 cu un cod plan_required și un indiciu de upgrade.
- 401 — cheia lipsește, este malformată sau revocată.
- 404 — grupul vizat nu există sau nu îi sunteți administrator.
- 403 plan_required — endpoint-ul necesită Pro sau superior pe acel grup.