Când merită API-ul REST, ce piese folosiți, ce limite de rată se aplică și cum securizați integrarea cu AI SNS CHAT, cu exemple pentru firme din România.
Aveți un magazin online, o clinică sau un service și vreți ca agentul AI să se conecteze la sistemele dumneavoastră: comenzi, programări, un CRM făcut în casă. Canalele gata făcute acoperă mult, dar nu tot. În acest articol aflați când este API-ul REST unealta potrivită, din ce piese este alcătuit, ce limite trebuie respectate și ce verificări faceți înainte de lansare.
Când este API-ul unealta potrivită (și când nu este)
Prima întrebare nu este „cum folosesc API-ul?", ci „am nevoie de el?". Multe firme mici ajung la API prea devreme, deși o integrare existentă rezolvă aceeași problemă fără o singură linie de cod.
API-ul are sens atunci când:
- vreți ca agentul să răspundă într-o interfață proprie, de exemplu o aplicație mobilă sau un portal de clienți;
- sistemul dumneavoastră trebuie să primească automat evenimente (de exemplu o conversație predată unui om) și să facă ceva cu ele;
- aveți o aplicație internă, fără conector gata făcut, care trebuie să „vorbească" cu agentul;
- vreți un control fin asupra afișării răspunsurilor, inclusiv a celor transmise pe măsură ce se generează.
API-ul nu este necesar atunci când vreți doar:
- un widget de chat pe site;
- agentul pe WhatsApp, Messenger sau Instagram;
- predarea către un coleg prin Slack, Teams sau e-mail;
- legarea la Shopify, Stripe, Google Sheets sau HubSpot.
Pentru toate acestea există canale și integrări în platformă, configurabile din interfață.
Piesele de bază
API-ul AI SNS CHAT este un API REST care lucrează cu JSON. Pentru integrările obișnuite aveți nevoie de patru elemente.
Cheia API
Se creează din setările spațiului de lucru, la secțiunea pentru chei API. Cheia se afișează o singură dată, deci o salvați imediat într-un loc sigur. O puteți revoca oricând, iar disponibilitatea ei depinde de plan: este inclusă de la Hobby în sus.
Cererile JSON
Trimiteți mesajul clientului și primiți răspunsul agentului. Detaliile exacte (căi, câmpuri, exemple) se găsesc în referința API publicată. Nu le copiați din articole, ci din documentația oficială, care este sursa de adevăr.
Streaming prin SSE
Dacă adăugați parametrul stream=1, răspunsul vine în fragmente, prin Server-Sent Events. Utilizatorul vede textul apărând pe măsură ce este generat, nu după câteva secunde de așteptare. Pe o interfață proprie, diferența se simte imediat.
Webhook-uri semnate
Platforma poate trimite evenimente către adresa dumneavoastră, semnate prin HMAC, iar în panou există un jurnal de livrări. Semnătura vă permite să verificați că mesajul vine într-adevăr de la AI SNS CHAT și nu de la un terț.
- 01Clientul scrie în aplicația dumneavoastră
- 02Serverul dumneavoastră apelează API-ul cu cheia
- 03Agentul răspunde (opțional în flux SSE)
- 04Webhook semnat anunță sistemul dumneavoastră
Respectați limitele de rată publicate
Referința API publică trei limite, pe care le puteți planifica de la început:
| Zonă | Limită publicată |
|---|---|
| Autentificare | 20 de cereri la 5 minute, per adresă IP |
| Chat public | 30 de cereri pe minut, per adresă IP |
| Interogare periodică (poll) | 120 de cereri pe minut |
Trei consecințe practice:
- Serverul dumneavoastră este, de regulă, un singur IP. Dacă toate cererile clienților trec printr-un backend comun, limita pe IP se aplică cumulat pentru toți. Exemplu ipotetic: dacă 40 de vizitatori scriu simultan în același minut printr-un singur server, veți depăși plafonul de 30 de cereri pe minut pentru chatul public.
- Nu încercați autentificarea în buclă. Cu 20 de încercări la 5 minute, o buclă defectuoasă vă blochează singuri.
- Preferați webhook-urile interogării. Dacă așteptați un eveniment, un webhook consumă mai puține cereri decât un poll repetat.
Pentru volume mari, verificați întâi limitele în referința API și gândiți o coadă de mesaje în aplicația dumneavoastră. Nu inventați presupuneri despre plafoane care nu sunt publicate.
Tipare de proiectare care funcționează
Backend intermediar, nu cheie în browser
Cheia API nu trebuie să ajungă niciodată în codul de pe pagină sau în aplicația mobilă. Faceți apelul din serverul dumneavoastră, iar browserul vorbește doar cu serverul. Dacă un angajat pleacă sau cheia scapă, o revocați și o înlocuiți fără să atingeți aplicațiile clienților.
Streaming către interfața proprie
Backendul primește fluxul SSE și îl retransmite în interfață. Pentru un portal de clienți al unui service auto, de exemplu, utilizatorul vede răspunsul formându-se, iar impresia de viteză crește fără să schimbați nimic în agent.
Evenimente către sistemele interne
Un exemplu ipotetic: un magazin online primește un webhook când o conversație este predată unui om. Aplicația creează automat un tichet intern și notifică responsabilul de turn. Predarea în sine, cu repartizare pe ture, alerte în Slack, Teams, WhatsApp sau e-mail, există deja în platformă. API-ul adaugă doar legătura cu sistemul dumneavoastră.
Idempotență și reîncercări
Webhook-urile pot ajunge de două ori sau întârziat. Proiectați handlerul astfel încât procesarea repetată a aceluiași eveniment să nu producă efecte duble (de exemplu, două tichete pentru aceeași conversație). Jurnalul de livrări din panou vă ajută să vedeți ce s-a trimis și ce nu.
Separare între medii
Folosiți chei diferite pentru testare și producție. Așa o cheie de test compromisă nu afectează clienții reali.
Listă de verificare a securității înainte de lansare
- Cheia este păstrată doar pe server, într-un seif de secrete sau în variabile de mediu, nu în depozitul de cod.
- Verificați semnătura HMAC a fiecărui webhook înainte de a-l procesa. Respingeți orice cerere fără semnătură validă.
- Comunicați exclusiv prin HTTPS.
- Nu înregistrați în loguri chei, conținut de conversații sau date personale inutile.
- Aveți un plan de revocare: știți cine poate șterge o cheie și cum o înlocuiți fără întrerupere.
- Minimizați datele. Dacă trimiteți către agent un CNP, un IBAN sau date medicale, întrebați-vă dacă este cu adevărat necesar. GDPR este cadrul firesc de lucru în România, iar principiul minimizării datelor se aplică și integrărilor.
- Verificați accesul în echipă. Rolurile din spațiul de lucru și jurnalul de activitate (cine ce a creat sau modificat) ajută la urmărirea schimbărilor.
Practicile platformei sunt concepute cu referire la GDPR și APPI, dar responsabilitatea pentru integrarea scrisă de dumneavoastră rămâne a dumneavoastră. Detalii despre măsurile platformei găsiți pe pagina Securitate.
Testare și lansare treptată
- Începeți în Playground. Verificați comportamentul agentului (persona, sursele de cunoștințe, ton) înainte de orice cod. Dacă răspunsul este greșit în Playground, API-ul nu îl va îndrepta.
- Testați cu o cheie separată și cu un număr mic de utilizatori interni.
- Simulați erorile: o cheie revocată, un webhook cu semnătură greșită, depășirea unei limite. Aplicația trebuie să se comporte decent în fiecare caz.
- Lansați treptat. Activați integrarea pentru o parte dintre clienți sau pentru un singur canal și urmăriți jurnalul de livrări, conversațiile din Activity → Chat logs și consumul de credite din pagina Usage.
- Păstrați o cale de întoarcere. Dacă ceva nu merge, opriți integrarea personalizată și lăsați widgetul obișnuit să preia traficul.
Un exemplu ipotetic de calcul: dacă o firmă primește 300 de conversații pe lună și fiecare are în medie 6 răspunsuri ale agentului, rezultă aproximativ 1.800 de răspunsuri, deci 1.800 de credite (1 răspuns = 1 credit). Un calcul de acest fel, făcut înainte de lansare, arată dacă planul ales este suficient.
Cum procedați în AI SNS CHAT
Iată pașii concreți, în ordinea în care îi veți parcurge.
- Verificați planul. Cheile API necesită minimum planul Hobby. Prețurile curente le vedeți pe pagina Prețuri, pentru că ele se pot modifica.
- Construiți agentul. Creați-l cu asistentul ghidat, adăugați sursele din Data sources (fișiere, site, Q&A, Notion etc.) și testați-l în Playground. Puteți compara modele diferite în Playground A/B.
- Creați cheia. În Workspace settings → API keys generați o cheie nouă. Copiați-o imediat, deoarece se afișează o singură dată.
- Alegeți canalul „API". În Sidebar → Channels găsiți API în lista de canale, alături de widget, WhatsApp, Messenger, Instagram, Telegram și altele. Detalii despre toate găsiți la Conexiuni.
- Configurați webhook-urile. Adresa dumneavoastră primește evenimente semnate HMAC, iar livrările pot fi urmărite într-un jurnal.
- Folosiți streamingul (
stream=1) dacă vreți răspunsuri care apar treptat în interfața proprie. - Monitorizați. Conversațiile sunt în Activity → Chat logs, cu filtre, export și aprecieri pozitive/negative. Consumul pe agent apare în Usage. În Workspace settings → Activity, proprietarii și administratorii văd cine a creat sau modificat ce.
Dacă preluați conversația manual, agentul se oprește, iar dumneavoastră puteți corecta un răspuns și îl transformați în răspuns ideal pentru antrenare. Dacă ceva nu este clar în panou, Synthia, managerul AI al platformei, vă poate ghida și vă arată pe ecran unde se află fiecare control.
Aveți un site pe domeniul propriu? De la Hobby în sus puteți folosi domenii personalizate (Agent → Settings → Custom domains), ca scriptul de încorporare și linkul agentului să apară pe subdomeniul firmei.
Merită menționat și ce nu face API-ul: nu înlocuiește canalele existente. WhatsApp, Messenger și Instagram se activează din Channels, fără cod. Pe WhatsApp, campaniile de tip outbound respectă fereastra de 24 de ore și includ opțiunea STOP.
Concluzie
API-ul REST este util când nevoia dumneavoastră chiar nu se potrivește cu un canal sau cu o integrare existentă. Păstrați cheia pe server, verificați semnătura fiecărui webhook, respectați limitele publicate și lansați treptat. Pentru restul, panoul de control este mai rapid și mai ieftin de întreținut decât orice cod propriu.
Întrebări frecvente
De ce plan am nevoie pentru a folosi API-ul REST?
Cheile API sunt disponibile de la planul Hobby în sus. Prețurile pot fi ajustate de platformă, așa că verificați pagina de prețuri pentru valorile curente. Planul Free nu include chei API.
Pot transmite răspunsurile în flux în propria interfață?
Da. API-ul acceptă streaming prin Server-Sent Events, activat cu parametrul stream=1. Backendul dumneavoastră primește fragmentele și le retransmite în interfață, astfel încât utilizatorul vede textul apărând treptat.
Cum știu că un webhook vine cu adevărat de la AI SNS CHAT?
Webhook-urile sunt semnate prin HMAC. Calculați semnătura pe serverul dumneavoastră, cu secretul corespunzător, și respingeți orice cerere pentru care nu se potrivește. Detaliile exacte ale verificării sunt în referința API publicată. Jurnalul de livrări din panou vă arată ce s-a trimis.
Care sunt limitele de rată?
Limitele publicate sunt: autentificare, 20 de cereri la 5 minute per IP; chat public, 30 de cereri pe minut per IP; interogare periodică (poll), 120 de cereri pe minut. Dacă toate cererile pleacă de la același server, limitele per IP se aplică cumulat, deci planificați volumul în consecință.
Am nevoie de API pentru a pune un agent pe WhatsApp sau Messenger?
Nu. WhatsApp, Messenger, Instagram, Telegram și multe alte canale se configurează din Sidebar → Channels, fără cod. API-ul este necesar doar pentru integrări personalizate, de exemplu o interfață proprie sau un sistem intern fără conector.


