Referință API

API antifraudă

Un SDK de browser pentru identificare, webhook-uri semnate pentru evenimente în timp real și un Server API doar pentru citire, pentru istoric. Tot ce ai nevoie ca să oprești frauda la nivel de dispozitiv.

Obține cheia API API Playground

Endpoint-uri

SDK@tracio/sdk

Identifică un vizitator în browser cu SDK-ul client. Returnează un ID de vizitator stabil și un verdict de bot fără drum dus-întors către server. Cheia publică poate fi inclusă în siguranță în codul client-side.

Cerere

import { Tracio } from '@tracio/sdk'
const tracio = Tracio.init({ publicKey: '5ca175fc...' })
const result = await tracio.getResult()

Răspuns

{
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "bot": {
    "detected": false,
    "confidence": 2,
    "reasons": []
  }
}

POST/webhook/tracio

TRACIO livrează un eveniment semnat către endpoint-ul tău la fiecare identificare. Verifică antetul X-Tracio-Signature, apoi acționează pe baza payload-ului JSON plat. Aceasta este suprafața de push: nu trebuie să faci polling după ea. Dacă totuși ai nevoie să citești o vizită ulterior, Server API răspunde după requestId.

Cerere

POST /webhook/tracio HTTP/1.1
Host: your-server.com
Content-Type: application/json
X-Tracio-Payload-Version: 2
X-Tracio-Event-Type: identification
X-Tracio-Signature: t=1710432000,v1=5257a869e7ecebed...

Răspuns

{
  "version": 2,
  "event": "identification",
  "eventId": "9c1f4b2e-7d3a-4f18-8b6c-2e5a71d0c4f9:primary",
  "requestId": "9c1f4b2e-7d3a-4f18-8b6c-2e5a71d0c4f9",
  "phase": "primary",
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "timestamp": "2026-03-12T16:00:00Z",
  "bot": { "result": "human", "score": 2 },
  "identification": { "confidence": 0.95, "incognito": false },
  "network": { "vpn": false, "proxy": false, "tor": false, "datacenter": false },
  "decision": { "action": "real", "riskScore": 4 }
}

GET/.well-known/webhook-keys

Obține cheile publice Ed25519 ale platformei, folosite pentru verificarea livrărilor de webhook. Această rută nu necesită autentificare și este păstrată în cache cinci minute. Câmpul kid din antetul de semnătură îți spune ce cheie să folosești.

Cerere

curl https://api.tracio.ai/.well-known/webhook-keys

Răspuns

{
  "keys": [
    {
      "kid": "k1",
      "alg": "Ed25519",
      "publicKey": "MCowBQYDK2VwAyEA9tR2v1kQ..."
    }
  ]
}

GET/v1/visitors/{visitorId}

Citește istoricul unui vizitator din Server API cu cheia ta secretă. Disponibil începând cu planul Pro. Fereastra este limitată la planul tău, iar fereastra pe care ai primit-o efectiv este raportată în meta. Susține cererile de drept de acces conform GDPR.

Cerere

# Server API — available on the Pro plan and above
curl "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX"

Răspuns

{
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "firstSeenAt": "2026-03-01T08:11:00Z",
  "lastSeenAt": "2026-03-16T14:22:01Z",
  "visits": 12,
  "incognitoVisits": 1,
  "uniqueIps": 4,
  "uniqueCountries": 2,
  "risk": { "maxRiskScore": 63, "lastDecision": "real" },
  "network": {
    "vpnSeen": false,
    "proxySeen": false,
    "torSeen": false,
    "datacenterSeen": true
  },
  "meta": {
    "plan": "pro",
    "retentionDays": 30,
    "from": "2026-02-14T00:00:00Z",
    "to": "2026-03-16T14:30:00Z"
  }
}

Autentificare

TRACIO folosește trei credențiale, câte una per suprafață: o cheie publică pentru SDK-ul de browser, o cheie secretă (tracio_sk_…) trimisă ca Authorization: Bearer pentru Server API și un secret de semnare HMAC pentru a verifica livrările webhook. Cheia secretă este creată în panou, afișată o singură dată și nu trebuie să ajungă niciodată într-un browser — Server API nu returnează, în mod deliberat, niciun antet CORS.

# Client SDK — public key (safe to ship in the browser)
Tracio.init({ publicKey: '5ca175fc...' })
# Server API — secret key, created in the dashboard and shown once
Authorization: Bearer tracio_sk_XXXX...XXXX
# Webhook verification — HMAC-SHA256 over "<t>.<rawBody>"
X-Tracio-Signature: t=<unix>,v1=<hmac_sha256_hex>

Limite de rată

Limitele sunt per workspace. Apelurile Server API sunt contorizate separat de identificări, așa că citirea propriului istoric nu consumă niciodată cota pe care o plătești. Fiecare răspuns conține X-RateLimit-Limit, X-RateLimit-Remaining și X-RateLimit-Reset, plus Retry-After la un 429. Server API nu face parte din planul gratuit.

Plan	Rată Server API	Server API pe zi	Endpoint-uri webhook	Fereastră de interogare
Gratuit	Neinclus	Neinclus	0	7 days
Pro	10 req/s	10,000	5	30 days
Business	50 req/s	100,000	20	90 days
Enterprise	200 req/s	Nelimitat	100	365 days

Coduri de eroare

Fiecare eroare returnează același plic: un obiect error cu un cod de tip string, un mesaj lizibil pentru om și requestId-ul apelului eșuat.

400Bad RequestParametri de interogare malformați, o fereastră nesuportată sau un identificator care nu este un ID de vizitator valid.

401UnauthorizedCredențiale lipsă sau invalide — cheie publică (SDK), cheie secretă (Server API) sau semnătură webhook.

402Upgrade RequiredPlanul tău nu include acces la Server API. Începe de la planul Pro.

404Not FoundNiciun vizitator și nicio sesiune cu acel identificator în fereastra de interogare a planului tău.

405Method Not AllowedServer API este doar pentru citire. Fiecare rută răspunde la GET și la nimic altceva.

429Rate LimitedPrea multe cereri pe secundă sau cota zilnică este epuizată. Verifică antetul Retry-After și limitele planului tău.

500Internal ErrorEroare de server. Reîncearcă cu exponential backoff. Dacă persistă, contactează suportul cu requestId.

503Service UnavailableAPI-ul nu poate răspunde temporar. Reîncearcă cu exponential backoff.

Formatul răspunsului de eroare

{
  "error": {
    "code": "rate_limited",
    "message": "too many requests",
    "requestId": "8f14e45fceea167a5a36dedd"
  }
}

Începe să construiești

Obține cheia API și fă prima ta cerere de identificare în mai puțin de 5 minute.

Obține cheia API Documentația API completă