Data API

Data API (documentat aici anterior drept Server API) permite backend-ului tău să citească datele de identificare pe care TRACIO le-a colectat deja pentru workspace-ul tău: istoricul unui vizitator, sesiunile individuale și contoarele de velocity pe ferestre scurte. Câteva rute și scriu — înregistrări de cont, câmpuri personalizate și intrări în liste — pentru ca backend-ul tău să poată îmbogăți ceea ce știe TRACIO.

Completează Webhooks, fără să le înlocuiască:

Ambele suprafețe sunt disponibile începând cu planul Pro.

URL de bază

https://api.tracio.ai/v2

Acesta este un host diferit de endpoint-ul din browser (edge.tracio.ai) și de dashboard (app.tracio.ai). Toate trei sunt separate: browserul vorbește cu edge-ul folosind cheia ta publică, iar backend-ul tău vorbește cu Data API folosind cheia secretă.

Migrarea de la v1

Rutele /v1 au fost eliminate. Folosește /v2: rutele sunt aceleași, iar fiecare cheie JSON și fiecare parametru de query sunt în snake_case (visitor_id, risk_score, min_risk_score). Cheile din propriile tale dicționare fields și labels sunt datele tale și își păstrează scrierea originală. SDK-ul JavaScript își păstrează interfața în camelCase.

Autentificare

Fiecare cerere poartă cheia ta secretă ca bearer token:

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v2/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

Data API este exclusiv server-to-server. Antetele CORS nu sunt returnate în mod deliberat, așa că un browser nu o poate apela — tocmai asta ține cheia ta secretă în afara codului de pe client. Nu trimite niciodată cheia secretă în browser.

Obținerea unei chei secrete

Creeaz-o în dashboard, la API Keys, alegând tipul secret.

• Cheia completă este afișată exact o dată, la creare. De partea noastră se păstrează doar un hash, așa că o cheie pierdută nu poate fi recuperată — rotește-o în schimb.
• O cheie secretă arată ca tracio_sk_ urmat de 43 de caractere, 53 în total. Dashboard-ul o listează după primele câteva caractere, ca să poți deosebi cheile între ele.
• Cheile secrete necesită planul Pro sau mai mare; cheia publică folosită de agentul din browser este o valoare separată, nesecretă, de 40 de caractere.
• O cheie este legată de un mediu: o cheie de producție nu vede un vizitator din staging — răspunsul este 404, exact ca pentru datele care nu există.

Rotirea unei chei secrete

Rotirea emite o cheie nouă și o menține pe cea veche funcțională timp de 7 zile, ca să o poți desfășura fără întreruperi. Desfășoară cheia nouă, confirmă că traficul s-a mutat și las-o pe cea veche să expire. Cheile publice nu se pot roti — nu sunt secrete și sunt vizibile prin design în sursa paginii tale.

Endpoint-uri

Aceeași cheie și același host servesc și API-urile de decizie, toate în snake_case:

Rezultatele lor ajung la tine și ca evenimente webhook: transaction_state_changed, login_risk, trusted_device_enrolled, trusted_device_revoked și affiliate_threshold_crossed.

O bară finală este acceptată și ignorată. O cale necunoscută sau o metodă greșită returnează același plic JSON de eroare ca tot restul, niciodată o pagină HTML sau de text simplu.

Fereastra temporală

Fiecare citire este delimitată de o fereastră temporală, controlată prin doi parametri de query opționali:

• O dată simplă drept to include întreaga zi respectivă.
• Orice altceva este respins cu 400 invalid_request și mesajul time must be YYYY-MM-DD or RFC3339.
• Când nu transmiți niciunul dintre ele, fereastra este întreaga perioadă de retenție a planului tău, încheiată acum.
• O fereastră care ajunge mai departe în urmă decât permite planul tău este restrânsă în tăcere, nu respinsă. Fereastra folosită efectiv este întotdeauna raportată înapoi în meta, așa că verifică meta.from și meta.to în loc să presupui că cererea ta a fost onorată întocmai.

Căutarea unui vizitator

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v2/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

Răspunsul poartă istoricul agregat și include ultima sesiune, așa că în cazul obișnuit este nevoie de o singură cerere, nu de două:

{
  "visitor_id": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "first_seen_at": "2026-05-02T10:11:12Z",
  "last_seen_at": "2026-07-25T08:00:00Z",
  "visits": 42,
  "incognito_visits": 3,
  "unique_ips": 5,
  "unique_countries": 2,
  "browsers": ["Chrome"],
  "os": ["macOS"],
  "devices": ["desktop"],
  "risk": {
    "max_risk_score": 63,
    "avg_bot_score": 12.5,
    "bot_sessions": 7,
    "last_decision": "real"
  },
  "network": {
    "vpn_seen": false,
    "proxy_seen": false,
    "tor_seen": false,
    "datacenter_seen": true,
    "proxy_detected_seen": true,
    "last_isp": "Deutsche Telekom",
    "last_real_ip": { "address": "203.0.113.7", "country": "NL", "isp": "KPN" }
  },
  "last_session": {
    "request_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
    "visitor_id": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
    "account_id": "user_8842",
    "account": { "id": "user_8842", "email": "ann@example.com", "display_name": "Ann Lee" },
    "timestamp": "2026-07-25T08:00:00Z",
    "tag": "checkout",
    "fields": { "order_ref": "A-1029" },
    "url": "https://shop.example.com/checkout",
    "ip": "203.0.113.42",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "browser": { "name": "Chrome", "version": "126.0" },
    "os": { "name": "macOS", "version": "14.5" },
    "device": "desktop",
    "gpu": "Apple M2",
    "geo": {
      "country": "DE",
      "city": "Berlin",
      "timezone": "Europe/Berlin",
      "isp": "Deutsche Telekom"
    },
    "network": {
      "vpn": false,
      "proxy": false,
      "tor": false,
      "datacenter": false,
      "connection_type": "residential",
      "proxy_detected": true,
      "real_ip": { "address": "203.0.113.7", "country": "NL", "isp": "KPN" },
      "asn": 3320
    },
    "screen": { "width": 2560, "height": 1600, "color_depth": 30, "pixel_ratio": 2 },
    "locale": { "languages": ["en-US", "de"], "timezone": "Europe/Berlin" },
    "client_hints": { "architecture": "arm", "bitness": "64", "platform_version": "14.5.0" },
    "extensions": [
      {
        "slug": "ublock-origin",
        "name": "uBlock Origin",
        "category": "adblock",
        "risky": false,
        "store_url": "https://chromewebstore.google.com/detail/cjpalhdlnbpafiamejdnhcphjbkeiagm"
      }
    ],
    "bot": { "result": "human", "score": 4.5, "antidetect_score": 2.1 },
    "identification": {
      "confidence": 0.97,
      "incognito": false,
      "match_type": "exact",
      "match_confidence": 0.99
    },
    "device_info": {
      "device_id": "d_4f9c2e",
      "cross_browser": true,
      "confidence": 0.88,
      "linked_browsers": 2
    },
    "decision": { "action": "real", "risk_score": 12, "suspect_score": 3 }
  },
  "meta": {
    "plan": "business",
    "retention_days": 90,
    "from": "2026-04-26T00:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

Un vizitator fără date în fereastra de retenție returnează 404 not_found cu mesajul visitor not found in the retention window — nu este o eroare în integrarea ta, ci înseamnă că vizitatorul este nou sau a ieșit din fereastră odată cu trecerea timpului.

Câmpurile de verdict

Sesiunea poartă două verdicte, iar ele răspund la întrebări diferite — dacă clientul a fost automatizat și ce a concluzionat în ansamblu motorul de risc:

bot.score și decision.risk_score merg amândouă pe 0..100. Pe Business și peste, guidance le transformă în recomandări per scenariu, pe scara allow → challenge → review → deny — vezi Guidance pentru ce înseamnă fiecare treaptă. Valorile și scalele coincid cu corpul webhook-ului v3 pentru aceeași vizită, iar guidance este calculat după aceleași reguli.

Listarea sesiunilor unui vizitator

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v2/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y/sessions?limit=100&min_risk_score=50"

Sesiunile vin cu cele mai noi primele:

{
  "items": [
    {
      "request_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
      "visitor_id": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
      "timestamp": "2026-07-25T08:00:00Z"
    }
  ],
  "next_cursor": "MTcyMTg5NDQwMDAwMDphYmMxMjM",
  "has_more": true,
  "meta": {
    "plan": "business",
    "retention_days": 90,
    "from": "2026-04-26T00:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

Paginare

Paginarea se face pe bază de cursor. Nu există parametru page sau offset: trimite înapoi drept cursor valoarea next_cursor primită și continuă cât timp has_more este true. Ultima pagină poate să nu conțină deloc next_cursor, așa că nu face acest câmp obligatoriu.

async function allSessions(visitorId: string, secretKey: string) {
  const sessions = []
  let cursor: string | undefined

  do {
    const url = new URL(`https://api.tracio.ai/v2/visitors/${visitorId}/sessions`)
    url.searchParams.set("limit", "500")
    if (cursor) url.searchParams.set("cursor", cursor)

    const res = await fetch(url, { headers: { Authorization: `Bearer ${secretKey}` } })
    if (!res.ok) throw new Error(`Data API: ${res.status}`)

    const page = await res.json()
    sessions.push(...page.items)
    cursor = page.has_more ? page.next_cursor : undefined
  } while (cursor)

  return sessions
}

Tratează cursorul ca opac — conținutul lui este un detaliu de implementare și se poate schimba. Un cursor care a fost modificat este respins cu 400 invalid_request și mesajul malformed cursor.

Fapte despre dispozitiv

Pe lângă browserul și sistemul de operare luate din User-Agent, o sesiune poartă ceea ce browserul vizitatorului raportează despre mașină, curățat de partea noastră. Fiecare câmp lipsește când vizita nu a purtat astfel de date, așa că tratează-l pe fiecare drept opțional.

Extensii de browser

extensions enumeră extensiile de browser detectate în timpul vizitei — Pro și peste. Fiecare intrare este un obiect:

O constatare este raportată abia după ce a trecut de verificările noastre de încredere — un mediu care răspunde „instalat” la fiecare sondare sau un lot mai lung de douăsprezece nume este eliminat ca nesigur. Prin urmare, o listă goală sau lipsă înseamnă „nimic ce am putut confirma”, nu „nu există extensii instalate”. Citește-o ca pe o dovadă, nu ca pe un inventar.

Câmpuri personalizate

fields conține perechile cheie-valoare personalizate pe care integrarea ta le-a atașat vizitei — o referință de comandă, numele unui plan, rezultatul unei plăți. Cheile și valorile sunt întotdeauna șiruri: un număr sau o valoare booleană atașată revine sub formă de text. Ca restul sesiunii, câmpul este disponibil în orice plan cu acces la API (Pro și peste) și lipsește atunci când vizita nu are câmpuri.

fields este citit în timp real la fiecare cerere, nu copiat în momentul vizitei. Câmpurile atașate după vizită (vezi Atașarea câmpurilor după vizită) apar și ele aici, așa că pentru aceeași vizită fields poate conține mai mult decât a livrat webhook-ul.

Nu pune date personale, precum nume, adrese de e-mail sau numere de telefon, în câmpurile personalizate — atașează în schimb o referință pe care propriile tale sisteme o pot rezolva, iar cine este titularul contului trimite ca înregistrare de cont (mai jos).

Înregistrarea contului

account este înregistrarea ta pentru contul din spatele vizitei — ceea ce ai trimis ultima dată pentru acel account_id prin POST /v2/accounts/metadata:

{
  "account": { "id": "user-42", "email": "ann@example.com", "display_name": "Ann Lee" }
}

Înregistrarea este citită în timp real la fiecare cerere, așa că o redenumire apare și pe vizitele vechi: blocul descrie contul așa cum este acum, nu cum era în momentul vizitei. Este disponibilă în orice plan cu acces la API (Pro și peste). Etichetele trimise împreună cu înregistrarea nu sunt returnate.

Blocul lipsește când vizita nu are un cont asociat, când nu există o înregistrare pentru el (sau ai golit-o trimițând valori goale) și — rar — când înregistrarea nu a putut fi citită: sesiunea este totuși returnată integral, în loc ca cererea să eșueze, așa că tratează un bloc lipsă ca „necunoscut”, nu ca „acest cont nu are e-mail”. Webhook-urile nu poartă acest bloc.

Obținerea unei singure sesiuni

Cea mai recentă:

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v2/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y/sessions/latest"

Aceasta returnează un obiect sesiune simplu — nu un array și nu împachetat într-un plic. Un vizitator fără sesiuni în fereastră returnează 404 not_found cu no sessions for this visitor in the retention window.

Sau după request_id, identificatorul care apare și în payload-ul webhook-ului:

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v2/sessions/9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31?visitor_id=X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

visitor_id este opțional aici, dar transmiterea lui, atunci când îl cunoști, face căutarea vizibil mai rapidă.

identification.drift_score — scorul de comportament netezit pe baza căruia a fost dat verdictul de preluare a contului, Business și peste — este returnat doar de această citire a unei singure sesiuni. Deriva comportamentului se măsoară în timpul vizitei, după identificarea inițială, așa că rutele de listare și de ultimă sesiune îl omit. O vizită al cărei comportament nu a fost evaluat nu are drift_score. Aceeași valoare ajunge la tine prin webhook-ul account_takeover.

Ce răspuns primești pentru o vizită corectată

O vizită poate fi livrată prin webhook de mai multe ori: întâi primary, apoi late sau correction, pe măsură ce sosesc semnalele mai lente și dovezile comportamentale — iar o fază ulterioară poate răsturna verdictul anterior. Data API răspunde din înregistrarea primary. Fazele ulterioare nu sunt contopite înapoi în ea, așa că pentru o vizită corectată ultimul webhook este răspunsul mai nou. Dacă acționezi la câteva minute după vizită, preferă faza primită ultima unei citiri proaspete de aici.

Un lucru merge în sens invers: odată ce detectorul de preluare a conturilor s-a declanșat pentru o vizită, guidance de aici reflectă acest lucru, în timp ce corpurile webhook identification ale aceleiași vizite nu poartă acea axă — ea vine prin livrarea dedicată account_takeover.

Velocity

Velocity răspunde la întrebarea „cât de mult a făcut acest vizitator în ultima vreme” — forma pe care o au credential stuffing-ul, testarea de carduri și înregistrările în masă.

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v2/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y/velocity?window=1h"

window acceptă 1h, 24h sau 7d și are implicit 24h. Orice altă valoare este respinsă cu 400 invalid_request și window must be one of: 1h, 24h, 7d.

{
  "window": "1h",
  "events": 37,
  "unique_ips": 9,
  "unique_countries": 3,
  "unique_accounts": 12,
  "bot_events": 4,
  "meta": {
    "plan": "business",
    "retention_days": 90,
    "from": "2026-07-25T11:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

unique_accounts numără valorile linkedId distincte pe care le-ai trimis pentru acest dispozitiv — vezi Asocierea conturilor. bot_events este Business și peste; pe Pro cheia lipsește.

Metadatele conturilor

TRACIO îți cunoaște conturile doar după ID-ul pe care site-ul tău îl transmite ca linkedId — un șir opac precum usr_8412. Trimite o dată etichetele lizibile și fiecare ecran din dashboard care arată acel cont va afișa numele sau adresa de e-mail în locul ID-ului brut, iar obiectul sesiune le returnează în blocul său account. Nimic de aici nu afectează detectarea sau scorarea; este un strat de afișare.

curl -s -X POST "https://api.tracio.ai/v2/accounts/metadata" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
  -H "Content-Type: application/json" \
  -d '{"accounts":[
        {"account_id":"usr_8412","email":"ann@example.com","display_name":"Ann Lee","labels":{"tier":"vip"}},
        {"account_id":"usr_9130","display_name":"Bob Ray"}
      ]}'

{ "updated": 2 }

• Acesta este locul pentru datele personale despre un cont — nu fields. O adresă de e-mail sau un nume trimis aici trăiește doar în înregistrarea de cont a workspace-ului tău: nu este stocat per vizită, nu este scris în pagină, iar o singură trimitere actualizează fiecare vizită a acelui cont.
• Domeniul este workspace-ul și mediul cheii. O cheie de staging nu suprascrie niciodată ceea ce a scris o cheie de producție pentru același ID de cont.
• Fiecare trimitere este o suprascriere completă, nu un patch. Câmpurile omise sunt stocate goale — trimite de fiecare dată înregistrarea completă. Tot așa se și golește o valoare.
• Câmpurile necunoscute sunt respinse cu 400 invalid_request, iar o singură intrare greșită respinge întregul lot — eroarea îi indică poziția. ID-urile de cont duplicate într-un lot sunt în regulă: câștigă ultimul.

Limite: 1.000 de conturi per cerere, corp de 1 MiB, account_id ≤ 256 de caractere, email ≤ 320, display_name ≤ 256, cel mult 16 etichete, cu chei ≤ 64 și valori ≤ 256 de caractere.

Atașarea câmpurilor după vizită

Browserul poate trimite doar ceea ce pagina știe la randare — un ID de comandă, niciodată rezultatul unei verificări de plată sau orice altceva care se rezolvă mai târziu. Această rută acoperă golul: găsește vizita după un câmp pe care îl poartă deja și atașează-i mai multe câmpuri pe partea de server.

curl -s -X POST "https://api.tracio.ai/v2/events/fields" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
  -H "Content-Type: application/json" \
  -d '{"match":{"key":"order_ref","value":"A-1029"},"fields":{"amount":"120.00"}}'

{ "updated": 1 }

• match găsește vizita după un câmp pe care îl are deja, nu după request_id, în cadrul workspace-ului și mediului cheii tale.
• Fereastra de căutare este de 24 de ore. O vizită mai veche returnează 404 not_found — scrie câmpul la scurt timp după ce rezultatul se rezolvă.
• updated numără vizitele distincte. Trece de 1 doar când match atinge mai multe vizite — o pereche cheie/valoare care nu este unică pentru o comandă sau un coș. Un match care atinge mai mult de 100 de evenimente este refuzat cu 400 invalid_request, în loc să fie aplicat unui subset arbitrar.
• Câmpurile scrise aici apar în dashboard cu eticheta server și au prioritate față de o valoare cu aceeași cheie scrisă de browser.
• Lipsa unei potriviri este 404 not_found, nu un 200 gol.

Limitele sunt aceleași ca pentru canalul din browser: 50 de câmpuri per apel, chei ≤ 40 de octeți, valori ≤ 500 de octeți — octeți, nu caractere — setul de caractere al cheii A-Za-z0-9_.:-, corp de 1 MiB.

Ștergerea câmpurilor

Șterge câmpuri personalizate — niciodată vizita însăși. Folosește-o pentru valori pe care nu mai ai nevoie să le ții atașate unei vizite, cum ar fi totalul unei comenzi. Webhook-urile deja trimise și exporturile deja făcute nu se modifică.

# by request_id — clears every field on this one visit
curl -s -X POST "https://api.tracio.ai/v2/events/fields/delete" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31"}'

# by match — clears "order_ref" from every visit currently holding "A-1029"
curl -s -X POST "https://api.tracio.ai/v2/events/fields/delete" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
  -H "Content-Type: application/json" \
  -d '{"match":{"key":"order_ref","value":"A-1029"}}'

{ "deleted": 1 }

• request_id și match se exclud reciproc — trimiterea amândurora sau a niciunuia este 400 invalid_request. match folosește aceeași fereastră de 24 de ore și același plafon de 100 de evenimente ca atașarea.
• deleted numără câmpurile eliminate din vizită (după request_id) sau vizitele din care a fost eliminat câmpul (după match).
• Un nou apel, după ce nu a mai rămas nimic, returnează 404 not_found.

Listele workspace-ului

Aceleași liste pe care operatorii tăi le gestionează în dashboard, accesibile din propriul back office. Tipul unei liste este acțiunea ei asupra unei vizite care se potrivește — block, manual_review, challenge, allow — iar modul ei decide dacă acțiunea se aplică: observe doar numără potrivirile, enforce o aplică în guidance (axa list). Listele și modul lor se creează în dashboard; Data API citește listele și adaugă și elimină intrări.

curl -s "https://api.tracio.ai/v2/lists" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX"

[
  {
    "id": "7f3a9d2e-4c1b-4e8f-9a6d-1b2c3d4e5f60",
    "name": "Chargeback accounts",
    "type": "block",
    "mode": "enforce",
    "entries_count": 128
  }
]

# ban an account for 30 days
curl -s -X POST "https://api.tracio.ai/v2/lists/7f3a9d2e-4c1b-4e8f-9a6d-1b2c3d4e5f60/entries" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
  -H "Content-Type: application/json" \
  -d '{"value":"usr_8412","value_type":"linked_id","ttl_minutes":43200}'

{
  "id": "02b4c8d1-6e7f-4a90-b1c2-d3e4f5a6b7c8",
  "value": "usr_8412",
  "value_type": "linked_id",
  "expires_at": "2026-10-19T12:00:00Z",
  "propagation": "immediate"
}

Elimină o intrare cu același corp la POST /v2/lists/{list_id}/entries/delete; răspunsul este { "removed": true, "propagation": "immediate" }.

• value_type este ceea ce se compară cu valoarea: linked_id, visitor_id, device_id, ip, cidr sau country. O valoare care nu se poate interpreta pentru tipul ei este 400 invalid_request.
• Când se potrivesc mai multe liste, decide tipul cel mai specific — linked_id → visitor_id → device_id → ip → cidr → country — iar în cadrul lui câștigă acțiunea cea mai strictă.
• ttl_minutes este opțional. Dacă lipsește, se aplică TTL-ul implicit al listei; dacă nici acesta nu există, intrarea nu expiră niciodată (expires_at este null). Adăugarea din nou a unei intrări o reînnoiește.
• propagation spune când modificarea intră în vigoare: immediate sau ttl — în aproximativ cinci minute.
• Ștergerea unei valori care nu există este 200 cu removed: false; 404 este rezervat pentru o listă necunoscută.

Convenții de răspuns

Un câmp lipsă înseamnă „fără date”, niciodată zero. Câmpurile fără valoare sunt omise complet, în loc să fie trimise ca 0, "" sau null: un vizitator nou-nouț nu are match_confidence, o vizită curată nu are antidetect_score sau suspect_score. Singura excepție deliberată este bot.score, care este întotdeauna prezent, chiar și când este zero. Citește câmpurile defensiv.

Payload-ul depinde de planul tău. Accesul la API începe de la Pro, iar Pro primește sesiunea de bază — identificatori, timestamp, URL, IP, user agent, browser, sistem de operare, dispozitiv, geo, rețea, bot, identificare și decizie — împreună cu identification.match_type, identification.match_confidence, bot.score, bot.type, bot.antidetect_score, gpu, network.proxy_detected, extensions, fields și account. Business și Enterprise adaugă geo.isp, network.asn, network.real_ip, decision.suspect_score, identification.drift_score, reasons, behavior, guidance, device_info, spoofing, os_environment, screen, locale, client_hints și environment. Câmpurile la nivel de persoană (person_id, reputation, linked_accounts_count, linked_visitors_count) sunt rezervate pentru Business și Enterprise și vor apărea odată ce stratul de persoane va fi activat — astăzi acesta rulează în mod de observare, iar aceste câmpuri nu sunt livrate. Absența unui câmp Business pe un plan Pro nu este o eroare.

Detaliile interne la nivel de semnal nu sunt returnate niciodată, la niciun plan: numele semnalelor individuale, ponderile lor, pragurile din spatele unui verdict, valorile brute ale semnalelor și descompunerea scorurilor rămân de partea noastră. Un scor care poate fi supus ingineriei inverse până la intrările sale încetează să mai fie util ca apărare.

Erori

Fiecare eșec folosește un singur plic:

{
  "error": {
    "code": "unauthorized",
    "message": "missing Authorization: Bearer <secret key>",
    "request_id": "8f14e45fceea167a5a36dedd"
  }
}

Acest request_id nu este identificatorul vizitei. Două valori diferite poartă același nume: în payload-ul unei sesiuni, request_id este UUID-ul vizitei, același pe care îl livrează webhook-ul; în plicul unei erori, este un identificator de urmărire de 24 de caractere, generat pentru fiecare apel HTTP. Identificatorul de urmărire se întoarce și în antetul X-Request-Id la fiecare răspuns, reușit sau nu. Include-l când contactezi suportul — așa îți găsim apelul exact.

Verificările se fac într-o ordine fixă — cheia, apoi planul, apoi limitele — așa că o cerere cu o cheie greșită raportează întotdeauna mai întâi cheia, niciodată o problemă de cotă. Datele din alt workspace nu se pot deosebi de datele care nu există: ele dau 404, nu 403.

Două cazuri de 401 se citesc diferit în mod intenționat: missing Authorization: Bearer <secret key> înseamnă că antetul nu a sosit niciodată, în timp ce invalid or revoked API key înseamnă că a sosit și nu s-a potrivit. 402 poartă Data API requires the Pro plan or higher.

Reîncearcă 429 și 503 cu o pauză tot mai mare; reîncercarea altor 4xx nu are rost — ele înseamnă că cererea însăși trebuie corectată.

Limite de solicitări și cote

Răspunsurile pentru care cheia a fost recunoscută poartă situația ta curentă (răspunsurile 401 și 402 nu o poartă, iar Enterprise, fără cotă zilnică, nu primește antete de cotă):

• Rafalele scurte sunt permise: limita pe secundă este un token bucket care tolerează până la de trei ori rata susținută înainte să înceapă să refuze.
• O cerere refuzată pentru depășirea ratei pe secundă nu consumă cota zilnică, așa că o rafală nu poate mânca bugetul zilei.
• Limitele Data API sunt contorizate separat de traficul de identificare. Citirea propriului istoric nu consumă niciodată identificările pe care le plătești.

Pași următori

• Webhooks — primește fiecare identificare pe măsură ce se produce
• Asocierea conturilor — atașează propriul id de cont unui dispozitiv
• Detectarea boților — cum este produs verdictul de bot
• Confidențialitate și GDPR — gestionarea cererilor persoanelor vizate