Data API

Data API (dříve zde dokumentované jako Server API) umožňuje vašemu backendu číst identifikační data, která už TRACIO pro váš workspace nasbíralo: historii návštěvníka, jednotlivé relace a čítače velocity za krátká okna. Několik rout také zapisuje (záznamy účtů, vlastní pole a položky seznamů), takže váš backend může obohatit to, co TRACIO ví.

Doplňuje Webhooky, nenahrazuje je:

Obě rozhraní jsou k dispozici od plánu Pro výše.

Základní URL

https://api.tracio.ai/v2

Jde o jiný host než endpoint pro prohlížeč (edge.tracio.ai) a než dashboard (app.tracio.ai). Všechny tři jsou oddělené: prohlížeč mluví s edge pomocí vašeho veřejného klíče, váš backend mluví se Data API pomocí vašeho tajného klíče.

Přechod z v1

Routy /v1 byly odstraněny. Používejte /v2: routy jsou stejné a každý klíč JSON i parametr dotazu je ve snake_case (visitor_id, risk_score, min_risk_score). Klíče uvnitř vašich vlastních slovníků fields a labels jsou vaše data a zachovávají původní zápis. JavaScriptové SDK si ponechává rozhraní v camelCase.

Autentizace

Každý požadavek nese váš tajný klíč jako bearer token:

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

Data API je výhradně server-to-server. Hlavičky CORS se záměrně nevracejí, takže ji prohlížeč nemůže zavolat — právě to drží váš tajný klíč mimo kód na straně klienta. Tajný klíč nikdy neposílejte do prohlížeče.

Získání tajného klíče

Vytvořte jej v dashboardu v sekci API Keys a zvolte typ secret.

• Celý klíč se zobrazí právě jednou, při vytvoření. Na naší straně je uložen jen hash, takže ztracený klíč nelze obnovit — místo toho jej rotujte.
• Tajný klíč vypadá jako tracio_sk_ následované 43 znaky, celkem 53. Dashboard jej vypisuje podle prvních několika znaků, abyste klíče od sebe rozeznali.
• Tajné klíče vyžadují plán Pro nebo vyšší; veřejný klíč, který používá agent v prohlížeči, je samostatná, netajná hodnota o 40 znacích.
• Klíč je vázán na prostředí: produkční klíč nevidí návštěvníka ze stagingu — odpovědí je 404, přesně jako u dat, která neexistují.

Rotace tajného klíče

Rotace vydá nový klíč a starý nechá funkční ještě 7 dní, takže jej můžete nasadit bez výpadku. Nasaďte nový klíč, ověřte, že se provoz přesunul, a nechte starý vypršet. Veřejné klíče rotovat nelze — nejsou to tajemství a ve zdroji vaší stránky jsou vidět záměrně.

Endpointy

Stejný klíč a host obsluhují také rozhodovací API, všechna ve snake_case:

Jejich výsledky k vám dorazí také jako události webhooků: transaction_state_changed, login_risk, trusted_device_enrolled, trusted_device_revoked a affiliate_threshold_crossed.

Koncové lomítko se přijímá a ignoruje. Neznámá cesta nebo špatná metoda vrací stejnou chybovou JSON obálku jako všechno ostatní, nikdy HTML stránku ani prostý text.

Časové okno

Každé čtení je ohraničeno časovým oknem, které řídí dva volitelné parametry dotazu:

• Samotné datum v to zahrnuje celý ten den.
• Cokoli jiného je odmítnuto s 400 invalid_request a zprávou time must be YYYY-MM-DD or RFC3339.
• Když nepředáte ani jeden, oknem je celá doba uchovávání vašeho plánu, končící teď.
• Okno sahající dál do minulosti, než váš plán dovoluje, se mlčky zkrátí, místo aby bylo odmítnuto. Skutečně použité okno se vždy vrací v meta, takže kontrolujte meta.from a meta.to, místo abyste předpokládali, že váš požadavek byl splněn doslova.

Vyhledání návštěvníka

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

Odpověď nese agregovanou historii a vkládá do sebe poslední relaci, takže běžný případ potřebuje jeden požadavek místo dvou:

{
  "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"
  }
}

Návštěvník bez dat uvnitř okna uchovávání vrací 404 not_found se zprávou visitor not found in the retention window — to není chyba ve vaší integraci, znamená to, že návštěvník je nový nebo mu data stářím vypadla z okna.

Pole verdiktu

Relace nese dva verdikty a každý odpovídá na jinou otázku — zda byl klient automatizovaný a k čemu celkově dospěl rizikový engine:

bot.score i decision.risk_score běží na škále 0..100. Na Business a vyšších z nich guidance dělá doporučení pro jednotlivé scénáře na žebříčku allow → challenge → review → deny — význam jednotlivých příček najdete v části Guidance. Hodnoty a škály odpovídají tělu webhooku v3 pro tutéž návštěvu a guidance se počítá podle stejných pravidel.

Výpis relací návštěvníka

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

Relace se vracejí od nejnovějších:

{
  "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"
  }
}

Stránkování

Stránkuje se pomocí kurzoru. Parametr page ani offset neexistuje: pošlete zpět next_cursor, který jste dostali, jako cursor, a pokračujte, dokud je has_more true. Poslední stránka nemusí next_cursor obsahovat vůbec, proto toto pole nedělejte povinným.

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
}

Ke kurzoru se chovejte jako k neprůhlednému — jeho obsah je implementační detail a může se změnit. Upravený kurzor je odmítnut s 400 invalid_request a zprávou malformed cursor.

Fakta o zařízení

Vedle prohlížeče a operačního systému převzatých z User-Agent nese relace to, co prohlížeč návštěvníka hlásí o stroji, očištěné na naší straně. Každé pole chybí, když návštěva taková data nepřinesla, proto s každým počítejte jako s volitelným.

Rozšíření prohlížeče

extensions vypisuje rozšíření prohlížeče zjištěná během návštěvy — Pro a vyšší. Každá položka je objekt:

Nález se hlásí teprve poté, co prošel našimi kontrolami důvěryhodnosti — prostředí, které na každou sondu odpoví „nainstalováno“, nebo dávka delší než dvanáct názvů se zahazuje jako nespolehlivá. Prázdný nebo chybějící seznam tedy znamená „nic, co bychom mohli potvrdit“, ne „žádná rozšíření nejsou nainstalována“. Čtěte jej jako doklad, ne jako inventář.

Vlastní pole

fields obsahuje vlastní páry klíč–hodnota, které vaše integrace připojila k návštěvě — číslo objednávky, název plánu, výsledek platby. Klíče i hodnoty jsou vždy řetězce: připojené číslo nebo logická hodnota se vrací v textové podobě. Stejně jako zbytek relace je pole dostupné v každém plánu s přístupem k API (Pro a vyšší) a chybí, pokud návštěva žádná pole nemá.

fields se čte živě při každém požadavku, nekopíruje se v okamžiku návštěvy. Pole připojená po návštěvě (viz Připojení polí po návštěvě) se zde také objeví, takže pro tutéž návštěvu může fields obsahovat víc, než doručil webhook.

Do vlastních polí nevkládejte osobní údaje, jako jsou jména, e-mailové adresy nebo telefonní čísla — místo nich připojte odkaz, který dokážou dohledat vaše vlastní systémy, a to, kdo je majitelem účtu, pošlete jako záznam účtu (níže).

Záznam účtu

account je váš záznam o účtu stojícím za návštěvou — to, co jste pro dané account_id naposledy poslali přes POST /v2/accounts/metadata:

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

Záznam se čte živě při každém požadavku, takže přejmenování se projeví i u starých návštěv: blok popisuje účet tak, jak je teď, ne jak byl v okamžiku návštěvy. Je dostupný v každém plánu s přístupem k API (Pro a vyšší). Štítky, které jste se záznamem poslali, se nevracejí.

Blok chybí, když návštěva nemá propojený účet, když pro něj neexistuje záznam (nebo jste jej vymazali odesláním prázdných hodnot) a — výjimečně — když záznam nebylo možné načíst: relace se přesto vrátí celá, místo aby požadavek selhal, proto chybějící blok chápejte jako „neznámo“, ne jako „tento účet nemá e-mail“. Webhooky tento blok nenesou.

Načtení jedné relace

Té nejnovější:

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

Vrací holý objekt relace — ne pole a ne zabalený v obálce. Návštěvník bez relací v okně vrací 404 not_found s no sessions for this visitor in the retention window.

Nebo podle request_id, identifikátoru, který se objevuje i v payloadu webhooku:

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

visitor_id je zde volitelné, ale když jej znáte, jeho předání vyhledávání výrazně zrychlí.

identification.drift_score — vyhlazené skóre chování, na jehož základě padl verdikt o převzetí účtu, Business a vyšší — vrací pouze toto čtení jedné relace. Drift chování se měří během návštěvy, až po prvotní identifikaci, proto jej routy seznamu a nejnovější relace vynechávají. Návštěva, jejíž chování nebylo nikdy posouzeno, drift_score nemá. Stejná hodnota k vám dorazí i přes webhook account_takeover.

Jakou odpověď dostanete u opravené návštěvy

Návštěva může být webhookem doručena víckrát: nejprve primary, poté late nebo correction, jak přicházejí pomalejší signály a behaviorální doklady — a pozdější fáze může dřívější verdikt zvrátit. Data API odpovídá ze záznamu primary. Pozdější fáze se do něj zpětně neslučují, takže u opravené návštěvy je novější odpovědí poslední webhook. Pokud jednáte minuty po návštěvě, dejte přednost fázi, kterou jste dostali naposledy, před novým čtením zde.

Jedna věc funguje opačně: jakmile pro návštěvu zareagoval detektor převzetí účtu, guidance zde to zohledňuje, zatímco těla webhooků identification téže návštěvy tuto osu nenesou — ta jede ve vyhrazeném doručení account_takeover.

Velocity

Velocity odpovídá na otázku „kolik toho tento návštěvník poslední dobou dělá“ — tedy na tvar credential stuffingu, testování karet a hromadných registrací.

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

window přijímá 1h, 24h nebo 7d a výchozí hodnota je 24h. Jakákoli jiná hodnota je odmítnuta s 400 invalid_request a 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 počítá odlišné hodnoty linkedId, které jste pro toto zařízení poslali — viz Propojení účtů. bot_events je Business a vyšší; na plánu Pro klíč chybí.

Metadata účtů

TRACIO zná vaše účty jen podle ID, které váš web předává jako linkedId — neprůhledný řetězec jako usr_8412. Pošlete jednou čitelné popisky a každá obrazovka dashboardu, která daný účet zobrazuje, ukáže místo surového ID jméno nebo e-mail; objekt relace je vrací ve svém bloku account. Nic z toho neovlivňuje detekci ani skórování; jde o zobrazovací vrstvu.

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 }

• Sem patří osobní údaje o účtu — ne do fields. E-mail nebo jméno poslané sem žije jen v záznamu účtu vašeho workspace: neukládá se u jednotlivých návštěv, nezapisuje se do stránky a jedno odeslání aktualizuje každou návštěvu daného účtu.
• Rozsahem je workspace a prostředí klíče. Klíč ze stagingu nikdy nepřepíše to, co pro stejné ID účtu zapsal produkční klíč.
• Každé odeslání je úplný přepis, ne záplata. Vynechaná pole se uloží prázdná — pokaždé posílejte celý záznam. Stejně tak hodnotu i vymažete.
• Neznámá pole jsou odmítnuta s 400 invalid_request a jedna chybná položka odmítne celou dávku — chyba uvede její pozici. Duplicitní ID účtů v jedné dávce nevadí: platí poslední.

Limity: 1000 účtů na požadavek, tělo 1 MiB, account_id ≤ 256 znaků, email ≤ 320, display_name ≤ 256, nejvýše 16 štítků s klíči ≤ 64 a hodnotami ≤ 256 znaků.

Připojení polí po návštěvě

Prohlížeč může poslat jen to, co stránka ví v okamžiku vykreslení — číslo objednávky, nikdy výsledek kontroly platby ani nic jiného, co se rozhodne později. Tato routa zaplňuje tuto mezeru: najděte návštěvu podle pole, které už nese, a připojte k ní další pole na straně serveru.

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 najde návštěvu podle pole, které už má, ne podle request_id, v rámci workspace a prostředí vašeho klíče.
• Okno hledání je 24 hodin. Starší návštěva vrací 404 not_found — zapište pole brzy poté, co se výsledek rozhodne.
• updated počítá odlišné návštěvy. Přesáhne 1 jen tehdy, když váš match zasáhne víc než jednu návštěvu — pár klíč/hodnota, který není jedinečný pro jednu objednávku nebo košík. match, který zasáhne víc než 100 událostí, je odmítnut s 400 invalid_request, místo aby se uplatnil na libovolnou podmnožinu.
• Pole zapsaná zde se v dashboardu zobrazují se štítkem server a mají přednost před hodnotou se stejným klíčem zapsanou prohlížečem.
• Žádná shoda znamená 404 not_found, ne prázdné 200.

Limity odpovídají kanálu prohlížeče: 50 polí na volání, klíče ≤ 40 bajtů, hodnoty ≤ 500 bajtů — bajtů, ne znaků — znaková sada klíče A-Za-z0-9_.:-, tělo 1 MiB.

Mazání polí

Maže vlastní pole — nikdy samotnou návštěvu. Použijte jej pro hodnoty, které už u návštěvy nepotřebujete mít připojené, například celkovou částku objednávky. Již odeslané webhooky a již pořízené exporty se nemění.

# 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 a match se vzájemně vylučují — poslat obojí nebo ani jedno znamená 400 invalid_request. match používá stejné 24hodinové okno a stejný strop 100 událostí jako připojování.
• deleted počítá pole odebraná z návštěvy (podle request_id) nebo návštěvy, ze kterých bylo pole odebráno (podle match).
• Opakované volání, když už nic nezbývá, vrací 404 not_found.

Seznamy workspace

Tytéž seznamy, které vaši operátoři spravují v dashboardu, dostupné z vašeho vlastního back office. Typ seznamu je jeho akcí vůči odpovídající návštěvě — block, manual_review, challenge, allow — a jeho režim rozhoduje, zda se akce uplatní: observe shody jen počítá, enforce ji uplatňuje v guidance (osa list). Seznamy a jejich režim se vytvářejí v dashboardu; Data API seznamy čte a přidává a odebírá položky.

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"
}

Položku odeberete stejným tělem na POST /v2/lists/{list_id}/entries/delete; odpovědí je { "removed": true, "propagation": "immediate" }.

• value_type určuje, s čím se hodnota porovnává: linked_id, visitor_id, device_id, ip, cidr nebo country. Hodnota, kterou nelze pro její typ zpracovat, znamená 400 invalid_request.
• Když odpovídá několik seznamů, rozhoduje nejkonkrétnější typ — linked_id → visitor_id → device_id → ip → cidr → country — a v jeho rámci vyhrává nejpřísnější akce.
• ttl_minutes je volitelné. Když jej vynecháte, platí výchozí TTL seznamu; bez něj položka nikdy nevyprší (expires_at je null). Opětovné přidání položku obnoví.
• propagation říká, kdy se změna projeví: immediate, nebo ttl — zhruba do pěti minut.
• Smazání hodnoty, která v seznamu není, vrací 200 s removed: false; 404 je vyhrazeno pro neznámý seznam.

Konvence odpovědí

Chybějící pole znamená „žádná data“, nikdy nulu. Pole bez hodnoty se zcela vynechávají, místo aby se posílala jako 0, "" nebo null: zbrusu nový návštěvník nemá match_confidence, čistá návštěva nemá antidetect_score ani suspect_score. Jedinou záměrnou výjimkou je bot.score, které je přítomno vždy, i když je nulové. Pole čtěte obezřetně.

Payload závisí na vašem plánu. Přístup k API začíná na plánu Pro a Pro dostává základní relaci — identifikátory, časové razítko, URL, IP, user agent, prohlížeč, operační systém, zařízení, geo, síť, bot, identifikaci a rozhodnutí — spolu s identification.match_type, identification.match_confidence, bot.score, bot.type, bot.antidetect_score, gpu, network.proxy_detected, extensions, fields a account. Business a Enterprise přidávají 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 a environment. Pole na úrovni osoby (person_id, reputation, linked_accounts_count, linked_visitors_count) jsou vyhrazena pro Business a Enterprise a objeví se, jakmile bude vrstva osob zapnuta — dnes běží v režimu pozorování a tato pole se nedoručují. Chybějící pole z plánu Business na plánu Pro není chyba.

Vnitřnosti na úrovni signálů se nevracejí nikdy, v žádném plánu: názvy jednotlivých signálů, jejich váhy, prahy stojící za verdiktem, surové hodnoty signálů i rozpad skóre zůstávají na naší straně. Skóre, které lze zpětně rozložit na své vstupy, přestává být užitečné jako obrana.

Chyby

Každé selhání používá jednu obálku:

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

Toto request_id není identifikátor návštěvy. Stejné jméno nesou dvě různé hodnoty: uvnitř payloadu relace je request_id UUID návštěvy, totéž, které doručuje webhook; uvnitř chybové obálky jde o 24znakový identifikátor trasování, vytvořený pro každé HTTP volání. Identifikátor trasování se vrací i v hlavičce X-Request-Id u každé odpovědi, úspěšné i neúspěšné. Uveďte jej, když se obracíte na podporu — právě podle něj vaše konkrétní volání najdeme.

Kontroly probíhají v pevném pořadí — klíč, pak plán, pak limity — takže požadavek se špatným klíčem hlásí vždy nejdřív klíč, nikdy problém s kvótou. Data z jiného workspace jsou k nerozeznání od dat, která neexistují: vrací 404, ne 403.

Dva případy 401 se čtou záměrně jinak: missing Authorization: Bearer <secret key> znamená, že hlavička nikdy nedorazila, zatímco invalid or revoked API key znamená, že dorazila a neodpovídala. 402 nese Data API requires the Pro plan or higher.

429 a 503 opakujte s rostoucí pauzou; opakovat ostatní 4xx nemá smysl — znamenají, že je potřeba opravit samotný požadavek.

Omezení počtu požadavků a kvóty

Odpovědi, u kterých byl klíč rozpoznán, nesou váš aktuální stav (odpovědi 401 a 402 jej nenesou a Enterprise, který nemá denní kvótu, hlavičky kvóty nedostává):

• Krátké nárazy jsou povolené: limit za sekundu je token bucket, který snese až trojnásobek trvalé rychlosti, než začne odmítat.
• Požadavek odmítnutý za překročení rychlosti za sekundu nespotřebuje denní kvótu, takže náraz nemůže sníst rozpočet dne.
• Limity Data API se počítají odděleně od identifikačního provozu. Čtení vlastní historie nikdy neutratí identifikace, které platíte.

Další kroky

• Webhooky — přijímejte každou identifikaci ve chvíli, kdy nastane
• Propojení účtů — připojte vlastní id účtu k zařízení
• Detekce botů — jak vzniká verdikt o botovi
• Soukromí a GDPR — vyřizování žádostí subjektů údajů