Datele tale, acolo unde iei decizia
Fiecare identificare poate ajunge în sistemele tale în două feluri: împinsă către serverul tău în clipa în care se produce sau cerută de tine exact în secunda în care decizi. Ambele canale poartă aceleași cifre — iar asta este garantată de un test, nu de o promisiune.
Push sau pull
Webhook-urile îți împing evenimentele pe măsură ce se întâmplă. Data API îți permite să întrebi în momentul în care ai nevoie de un răspuns. Majoritatea echipelor le folosesc pe amândouă: webhook-uri ca să înregistreze și să reacționeze, Data API pentru verificarea în linie.
Webhook-uri — push, în timp real
Trimitem prin POST un eveniment JSON semnat către endpointul tău în clipa în care se întâmplă ceva: un vizitator este identificat, este semnalată o preluare de cont, începe un atac de boți. Nimic de interogat periodic, nimic de programat.
Cel mai potrivit pentru: înregistrarea fiecărei vizite, reacția la atacuri, alimentarea depozitului tău de date sau a SIEM-ului.
Latență de livrare p50 de 44–140 ms, de la eveniment la endpointul tău.
Data API — pull, la cerere
O API privată de la server la server. Backendul tău se autentifică cu o cheie secretă și citește exact ce știm despre un vizitator în secunda în care decide — de obicei într-un handler de autentificare sau de checkout.
Cel mai potrivit pentru: o verificare în linie înainte să taxezi un card, să aprobi o înscriere sau să deblochezi un cont.
Disponibil începând cu planul Pro.
Patru tipuri de eveniment, un singur plic
Fiecare livrare sosește în același plic, cu tipul evenimentului în corp și în headerul X-Tracio-Event-Type — așa că un singur handler poate ruta toate cele patru tipuri.
Vizitator identificat
Evenimentul central: o vizită a fost evaluată. Poartă ID-ul vizitatorului, browserul și sistemul de operare, geolocalizarea și rețeaua, verdictul despre boți și decizia de risc. Este livrat în faze — un eveniment principal la încărcarea paginii, apoi o fază târzie sau de corecție, atunci când dovezi mai lente schimbă verdictul. Corelează fazele după requestId.
identificationPreluare de cont
Detectorul de preluare a conturilor s-a declanșat pe o vizită: dispozitivul din spatele unui cont cunoscut nu mai seamănă cu dispozitivul care îl deține. Sosește ca eveniment propriu, cu contextul contului atașat, în loc să se ascundă într-un corp de identificare.
account_takeoverAtac de boți
Un val de trafic automat pe workspace-ul tău. Acesta nu are o vizită în spate — este o alertă la nivel de workspace, așa că blocurile despre vizită lipsesc pur și simplu din corp, în loc să sosească drept coji goale cu scoruri puse pe zero.
attack_detectedSchimbare de reputație
Un profil s-a mutat între benzile de reputație. Același plic ca la alerta de atac — un eveniment la nivel de profil, fără vizită atașată, care poartă banda nouă și pe cea anterioară.
reputation_changedO livrare, redusă la esențial
Acesta este corpul de bază. Pro adaugă velocitatea vizitelor; Business adaugă coduri de motiv pentru verdict, semnale comportamentale, guidance și date despre dispozitiv între browsere, în exact aceeași formă — apar blocuri noi, căile existente nu se mută niciodată.
{ "version": 2, "event": "identification", "eventId": "req_8f21c4:primary", "requestId": "req_8f21c4", "phase": "primary", "visitorId": "3f9a1b2c4d5e6f70", "timestamp": "2026-07-30T12:00:00Z", "geo": { "country": "DE", "city": "Berlin", "timezone": "Europe/Berlin" }, "network": { "vpn": true, "proxy": false, "tor": false, "datacenter": false }, "bot": { "result": "human", "score": 12 }, "identification": { "confidence": 0.97, "incognito": false }, "decision": { "action": "suspicious", "riskScore": 65.9 }}Fiecare cerere poartă două semnături
X-Tracio-Signature este un HMAC-SHA256 peste timestampul semnăturii lipit de corpul brut al cererii, cu cheia webhook-ului tău secret — dovedește că expeditorul cunoaște secretul pe care îl dețineți amândoi. X-Tracio-Signature-Ed25519 este semnătura platformei: o verifici cu o cheie publică luată de la un endpoint bine-cunoscut, deci la tine nu rămâne nimic secret de păstrat. Timestampul face parte din conținutul semnat, iar asta face inutilă reluarea unei capturi vechi.
Verifică pe octeții bruți ai cererii — un JSON reserializat schimbă octeții, iar semnătura nu se va potrivi. Reîncercările poartă același X-Tracio-Event-Id, deci deduplică după el.
Headere prezente la fiecare livrare
X-Tracio-Signature: t=1753444800,v1=5257a869e7ecebed...X-Tracio-Signature-Ed25519: t=1753444800,kid=k1,v1=0Zx0M0n8...X-Tracio-Event-Type: identificationX-Tracio-Event-Id: req_8f21c4:primaryX-Tracio-Delivery-Attempt: 1X-Tracio-Payload-Version: 2Construit ca să nu piardă evenimente
Livrarea rulează pe o flotă dedicată, iar sursa de adevăr este coada, nu memoria unui proces. Asta face reală garanția at-least-once: dacă un nod de livrare moare în zbor, evenimentul este în continuare în coadă și îl preia alt nod.
Reîncercări potrivite pentru pene reale
5 s, 30 s, 2 min, 10 min, 30 min, 2 h, 6 h. Primele reîncercări sosesc într-un minut, așa că o repornire scurtă a serviciului tău nu te costă nimic. Fiecare pauză este aleasă aleatoriu între jumătatea valorii listate și valoarea întreagă, ca reîncercările să nu revină ca o singură salvă după o pană.
Dezactivare automată care nu se declanșează aiurea
Un webhook este oprit doar când eșecurile ating pragul și durează de cel puțin 15 minute consecutive — o rafală de livrări din coadă în timpul unei reporniri nu omoară integrarea. Un 410 Gone dezactivează imediat. Dashboardul arată motivul, codul de răspuns și un buton de reactivare.
Rotația secretului fără pauză
După o rotație, ambele secrete rămân valabile 24 de ore, iar headerul poartă ambele semnături, deci este de ajuns ca una să se potrivească. Îți actualizezi configurația în interiorul ferestrei, în loc să alergi după o comutare bruscă; „Revocă acum” scurtează fereastra când ai nevoie să dispară imediat.
Un jurnal de livrări pe care îl poți citi
Fiecare încercare — cod de răspuns, durată, textul erorii — este vizibilă per webhook în dashboard, lângă o acțiune de test care trimite endpointului tău un payload de probă semnat, ca să îți poți confirma verificatorul înainte de a intra în producție.
Întreabă în momentul în care decizi
O API privată de la server la server, pe api.tracio.ai. Backendul tău se autentifică cu o cheie secretă și își citește propriile date. Nu trimite intenționat headere CORS: o cheie secretă dă acces la tot ce este în workspace-ul tău și nu trebuie să ajungă niciodată într-un browser. Disponibil începând cu planul Pro.
| Metodă | Cale | Returnează |
|---|---|---|
| GET | /v1/visitors/{visitorId} | Rezumatul vizitatorului: prima și ultima apariție, numărul de vizite, IP-uri și țări unice, browsere și dispozitive, istoricul de risc — plus cea mai recentă sesiune a lui. |
| GET | /v1/visitors/{visitorId}/sessions | Lista de sesiuni cu paginare prin cursor și filtre după interval de date, rezultatul verificării anti-bot și scorul minim de risc. |
| GET | /v1/visitors/{visitorId}/sessions/latest | Cea mai recentă sesiune, ca obiect unic, fără plic de listă. |
| GET | /v1/sessions/{requestId} | O anumită sesiune. Transmite și visitorId, iar căutarea trece prin indexul vizitatorilor, nu prin tot istoricul tău. |
| GET | /v1/visitors/{visitorId}/velocity | Activitatea pe o fereastră — 1h, 24h sau 7d: câte vizite, de la câte IP-uri, din câte țări, sub câte conturi. |
Verificarea unui vizitator la checkout
Apelul tipic: în handlerul tău de plată, înainte să autorizezi cardul. O cerere, un răspuns, iar blocul meta raportează fereastra pe care ai primit-o de fapt — dacă ceri șase luni, iar planul tău păstrează 30 de zile, returnează 30 de zile și o spune.
Cerere
# Inside your checkout handler, before you authorize the cardcurl -s -H "Authorization: Bearer $TRACIO_SECRET_KEY" \ "https://api.tracio.ai/v1/visitors/3f9a1b2c/velocity?window=24h"Răspuns
{ "window": "24h", "events": 128, "uniqueIps": 4, "uniqueCountries": 2, "uniqueAccounts": 1, "meta": { "plan": "business", "retentionDays": 30 }}Aceleași cifre peste tot
O vizită care are 65,9 în dashboardul tău are 65,9 în Data API și 65,9 în corpul webhook-ului. Două redări independente ar putea să se depărteze una de alta — scările sunt cazul clasic, un canal îți dă 0,93 acolo unde celălalt spune 93 — de aceea un test de paritate construiește o singură vizită, o redă prin ambele canale și compară câmpurile publice pe JSON brut. Potrivirea este impusă, nu afirmată.
Recomandări, nu doar cifre
Scorurile îți spun ce am văzut. Guidance îți spune ce să faci cu asta, pentru cele patru decizii care chiar costă bani — calculată de reguli versionate, cu raționamentul atașat.
Accepți plata?
Cântărește riscul, reputația de fraudă și verdictul despre boți înainte să autorizezi un card.
Accepți înscrierea?
Prinde contul de unică folosință înainte să existe — aici cântăresc cel mai mult multi-conturile și reputația.
Îl lași să intre?
Se strânge automat atunci când detectorul de preluare a conturilor s-a declanșat pe vizită.
Contorizezi conversia?
Separă o recomandare autentică de o auto-recomandare sau de un bot stimulat.
Un vocabular de patru cuvinte
Fiecare scenariu primește unul dintre patru răspunsuri și, odată cu el, temeiul pe care a fost emis — axele decisive dintr-un vocabular fix: bot, risc, reputație de fraudă, comportament, multi-conturi, preluare de cont, rețea, tipar de afiliere. Știi mereu ce axă a mișcat recomandarea, fără să vezi vreodată nume de semnale, ponderi sau praguri.
Un singur calcul, trei canale
Același bloc de guidance călătorește în webhook, răspunde în Data API și se afișează pe fișa vizitatorului în dashboard — un singur set de reguli, un singur rezultat, nicio reconciliere de partea ta. Citește recomandarea pentru scenariul tău, nu pe cea generală: cea generală este pur și simplu cea mai severă dintre cele patru, un rezumat pentru dashboarduri, nu o decizie de plată. Versiunea regulilor vine în payload, așa că o schimbare de reguli este ceva ce observi, nu ceva ce deduci dintr-o recomandare care s-a mutat.
"guidance": { "version": 1, "overall": "review", "payment": "review", "registration": "challenge", "login": "allow", "affiliate": "allow", "basis": ["risk", "fraud_reputation"]}Cinci SDK-uri pe front end, două canale pe back
Partea de browser vine ca cinci SDK-uri — JavaScript simplu, React, Vue 3, Angular și Svelte 5. Nu există SDK-uri de server, iar asta este intenționat: backendul tău se integrează pe HTTP simplu, prin webhook-uri semnate și prin Data API. Verificarea semnăturii încape într-o duzină de linii față de un vector de referință pe care îl publicăm, și nu rămâne nimic în plus de tot actualizat în arborele de dependențe al serverului tău.
Întrebări frecvente
Îl conectezi într-o după-amiază
Creează un webhook în dashboard, îndreaptă-l spre endpointul tău și apasă Test. Verifică semnătura față de vectorul nostru de referință și partea grea a rămas în urmă.