Server API

Server API pozwala Twojemu backendowi czytać dane identyfikacyjne, które TRACIO już zebrało dla Twojego workspace: historię odwiedzającego, pojedyncze sesje oraz liczniki aktywności z krótkiego okna.

Uzupełnia Webhooki, a nie zastępuje ich:

Obie powierzchnie są dostępne od planu Pro wzwyż.

Bazowy adres URL

https://api.tracio.ai/v1

To inny host niż endpoint przeglądarkowy (edge.tracio.ai) i niż panel (app.tracio.ai). Wszystkie trzy są osobne: przeglądarka rozmawia z edge Twoim kluczem publicznym, a Twój backend rozmawia z Server API Twoim kluczem sekretnym.

Uwierzytelnianie

Każde żądanie niesie Twój klucz sekretny jako token bearer:

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

Server API działa wyłącznie w trybie server-to-server. Nagłówki CORS celowo nie są zwracane, więc przeglądarka nie może go wywołać — właśnie to trzyma Twój klucz sekretny poza kodem klienckim. Nigdy nie wysyłaj klucza sekretnego do przeglądarki.

Jak uzyskać klucz sekretny

Utwórz go w panelu w sekcji API Keys, wybierając typ secret.

• Pełny klucz jest pokazywany dokładnie raz, przy tworzeniu. Po naszej stronie przechowywany jest wyłącznie hash, więc utraconego klucza nie da się odzyskać — zamiast tego go zrotuj.
• Klucz sekretny wygląda jak tracio_sk_ plus 43 znaki, łącznie 53. Panel wyświetla go po kilku pierwszych znakach, żebyś mógł odróżniać klucze od siebie.
• Klucze sekretne wymagają planu Pro lub wyższego; klucz publiczny, którego używa agent przeglądarkowy, to osobna, niesekretna wartość o długości 40 znaków.

Rotacja klucza sekretnego

Rotacja wydaje nowy klucz i utrzymuje stary w działaniu przez 7 dni, więc możesz go wdrożyć bez przestoju. Wdróż nowy klucz, potwierdź, że ruch się przeniósł, i pozwól staremu wygasnąć. Kluczy publicznych się nie rotuje — nie są sekretami i z założenia są widoczne w źródle Twojej strony.

Endpointy

Każda trasa to GET. W Server API nie ma operacji zapisu: czyta dane, a Twoja konfiguracja żyje w panelu.

Końcowy ukośnik jest akceptowany i ignorowany. Nieznana ścieżka lub zła metoda zwraca tę samą kopertę błędu w JSON co wszystko inne, nigdy stronę w HTML ani czystym tekście.

Okno czasowe

Każdy odczyt jest ograniczony oknem czasowym, którym sterują dwa opcjonalne parametry zapytania:

• Sama data jako to obejmuje cały ten dzień.
• Wszystko inne jest odrzucane kodem 400 invalid_request i komunikatem time must be YYYY-MM-DD or RFC3339.
• Gdy nie przekażesz żadnego z nich, oknem jest pełny okres przechowywania Twojego planu, kończący się teraz.
• Okno sięgające wstecz dalej, niż pozwala Twój plan, jest po cichu przycinane, a nie odrzucane. Faktycznie użyte okno zawsze wraca w meta, więc sprawdzaj meta.from i meta.to, zamiast zakładać, że Twoje żądanie zostało spełnione dosłownie.

Wyszukanie odwiedzającego

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

Odpowiedź niesie zagregowaną historię i osadza w sobie ostatnią sesję, więc typowy przypadek wymaga jednego żądania, a nie dwóch:

{
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "firstSeenAt": "2026-05-02T10:11:12Z",
  "lastSeenAt": "2026-07-25T08:00:00Z",
  "visits": 42,
  "incognitoVisits": 3,
  "uniqueIps": 5,
  "uniqueCountries": 2,
  "browsers": ["Chrome"],
  "os": ["macOS"],
  "devices": ["desktop"],
  "risk": {
    "maxRiskScore": 63,
    "avgBotScore": 12.5,
    "botSessions": 7,
    "lastDecision": "real"
  },
  "network": {
    "vpnSeen": false,
    "proxySeen": false,
    "torSeen": false,
    "datacenterSeen": true,
    "lastIsp": "Deutsche Telekom"
  },
  "lastSession": {
    "requestId": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
    "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
    "accountId": "user_8842",
    "timestamp": "2026-07-25T08:00:00Z",
    "tag": "checkout",
    "url": "https://shop.example.com/checkout",
    "ip": "203.0.113.42",
    "userAgent": "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",
    "geo": {
      "country": "DE",
      "city": "Berlin",
      "timezone": "Europe/Berlin",
      "isp": "Deutsche Telekom"
    },
    "network": {
      "vpn": false,
      "proxy": false,
      "tor": false,
      "datacenter": false,
      "asn": 3320
    },
    "bot": { "result": "human", "score": 4.5, "antidetectScore": 2.1 },
    "identification": {
      "confidence": 0.97,
      "incognito": false,
      "matchType": "exact",
      "matchConfidence": 0.99
    },
    "decision": { "action": "real", "riskScore": 12 }
  },
  "meta": {
    "plan": "business",
    "retentionDays": 90,
    "from": "2026-04-26T00:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

Odwiedzający, dla którego nie ma danych wewnątrz okna przechowywania, zwraca 404 not_found z komunikatem visitor not found in the retention window — to nie błąd w Twojej integracji, lecz znak, że odwiedzający jest nowy albo wypadł poza okres przechowywania.

Pola werdyktu

Sesja niesie dwa werdykty i odpowiadają one na różne pytania — czy klient był zautomatyzowany oraz do jakiego ogólnego wniosku doszedł silnik ryzyka:

bot.score i decision.riskScore mieszczą się oba w skali 0..100. W planach Business i wyżej guidance zamienia je w rekomendacje dla poszczególnych scenariuszy na drabinie allow → challenge → review → deny — co oznacza każdy szczebel, opisuje Guidance.

Lista sesji odwiedzającego

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

Sesje wracają od najnowszych:

{
  "items": [
    {
      "requestId": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
      "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
      "timestamp": "2026-07-25T08:00:00Z"
    }
  ],
  "nextCursor": "MTcyMTg5NDQwMDAwMDphYmMxMjM",
  "hasMore": true,
  "meta": {
    "plan": "business",
    "retentionDays": 90,
    "from": "2026-04-26T00:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

Paginacja

Stronicowanie opiera się na kursorach. Nie ma parametru page ani offset: przekaż otrzymany nextCursor z powrotem jako cursor i kontynuuj, dopóki hasMore jest prawdziwe.

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

  do {
    const url = new URL(`https://api.tracio.ai/v1/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(`Server API: ${res.status}`)

    const page = await res.json()
    sessions.push(...page.items)
    cursor = page.nextCursor
  } while (cursor)

  return sessions
}

Traktuj kursor jako nieprzezroczysty — jego zawartość jest szczegółem implementacyjnym i może się zmienić. Kursor, który został zmodyfikowany, jest odrzucany kodem 400 invalid_request i komunikatem malformed cursor.

Pobranie pojedynczej sesji

Ta najnowsza:

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

Zwracany jest goły obiekt sesji — nie tablica i nie opakowanie w kopertę. Odwiedzający bez sesji w oknie zwraca 404 not_found z komunikatem no sessions for this visitor in the retention window.

Albo po requestId, identyfikatorze, który pojawia się także w payloadzie webhooka:

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

visitorId jest tutaj opcjonalny, ale przekazanie go, gdy go znasz, wyraźnie przyspiesza wyszukiwanie.

Velocity

Velocity odpowiada na pytanie „ile ten odwiedzający ostatnio narobił” — tak właśnie wygląda upychanie danych logowania, testowanie kart i masowe rejestracje.

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

window przyjmuje 1h, 24h lub 7d, a domyślnie ma 24h. Każda inna wartość jest odrzucana kodem 400 invalid_request i komunikatem window must be one of: 1h, 24h, 7d.

{
  "window": "1h",
  "events": 37,
  "uniqueIps": 9,
  "uniqueCountries": 3,
  "uniqueAccounts": 12,
  "botEvents": 4,
  "meta": {
    "plan": "business",
    "retentionDays": 90,
    "from": "2026-07-25T11:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

uniqueAccounts liczy odrębne wartości linkedId, które wysłałeś dla tego urządzenia — zobacz Łączenie kont. botEvents jest dostępne od planu Business wzwyż.

Konwencje odpowiedzi

Brakujące pole oznacza „brak danych”, nigdy zero. Pola bez wartości są pomijane w całości, zamiast być wysyłane jako 0, "" czy null: zupełnie nowy odwiedzający nie ma matchConfidence, czysta wizyta nie ma antidetectScore ani suspectScore. Jedynym celowym wyjątkiem jest bot.score, które występuje zawsze, nawet gdy wynosi zero. Czytaj pola ostrożnie.

Payload zależy od Twojego planu. Każdy plan z dostępem do API dostaje bazową sesję — identyfikatory, znacznik czasu, URL, IP, user agent, przeglądarkę, system operacyjny, urządzenie, geo, sieć, bota, identyfikację i decyzję. Pro dokłada identification.matchType, identification.matchConfidence oraz bot.antidetectScore. Business i Enterprise dokładają geo.isp, network.asn, decision.suspectScore, identification.driftScore, reasons, behavior, guidance, deviceInfo oraz pola na poziomie osoby (personId, reputation, linkedAccountsCount, linkedVisitorsCount). Brak pola z poziomu Business w planie Pro nie jest błędem.

Wewnętrzne szczegóły na poziomie sygnałów nie są zwracane nigdy, w żadnym planie: nazwy poszczególnych sygnałów, ich wagi, progi stojące za werdyktem, surowe wartości sygnałów i rozbicia wskaźników zostają po naszej stronie. Wskaźnik, który da się odtworzyć wstecz do swoich danych wejściowych, przestaje być użyteczny jako zabezpieczenie.

Błędy

Każde niepowodzenie używa jednej koperty:

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

Ten requestId nie jest identyfikatorem wizyty. Nazwę dzielą dwie różne wartości: wewnątrz payloadu sesji requestId to UUID wizyty, ten sam, który dostarcza webhook; wewnątrz koperty błędu jest to 24-znakowy identyfikator śledzenia, wybijany dla każdego wywołania HTTP. Identyfikator śledzenia wraca również w nagłówku X-Request-Id przy każdej odpowiedzi, udanej czy nie. Dołącz go, kontaktując się ze wsparciem — właśnie po nim odnajdujemy Twoje konkretne wywołanie.

Kontrole biegną w ustalonej kolejności — klucz, potem plan, potem limity — więc żądanie ze złym kluczem zawsze zgłasza najpierw klucz, nigdy problem z kwotą.

Dwa przypadki 401 czyta się celowo inaczej: missing Authorization: Bearer <secret key> oznacza, że nagłówek w ogóle nie dotarł, a invalid or revoked API key — że dotarł i nie pasował. 402 niesie Data API requires the Pro plan or higher.

Limity zapytań i kwoty

Każda uwierzytelniona odpowiedź niesie Twój bieżący stan:

• Krótkie zrywy są dozwolone: limit na sekundę to token bucket, który toleruje do trzykrotności stałego tempa, zanim zacznie odmawiać.
• Żądanie odrzucone za przekroczenie tempa na sekundę nie zużywa kwoty dziennej, więc zryw nie może pochłonąć budżetu dnia.
• Limity Server API są liczone osobno od ruchu identyfikacyjnego. Odczyt własnej historii nigdy nie wydaje identyfikacji, za które płacisz.

Następne kroki

• Webhooki — odbieraj każdą identyfikację w chwili, gdy się dzieje
• Łączenie kont — dołącz własny identyfikator konta do urządzenia
• Wykrywanie botów — jak powstaje werdykt o bocie
• Prywatność i RODO — obsługa żądań osób, których dane dotyczą