Dokumentacja API

API antyfraudowe

Przeglądarkowy SDK do identyfikacji, podpisane webhooki do zdarzeń w czasie rzeczywistym oraz Server API tylko do odczytu do przeglądania historii. Wszystko, czego potrzebujesz, by powstrzymać oszustwa na poziomie urządzenia.

Uzyskaj klucz API API Playground

Endpointy

SDK@tracio/sdk

Zidentyfikuj odwiedzającego w przeglądarce za pomocą klienckiego SDK. Zwraca stabilne ID odwiedzającego i werdykt bota bez odwołania do serwera. Klucz publiczny można bezpiecznie umieścić w kodzie po stronie klienta.

Żądanie

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

Odpowiedź

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

POST/webhook/tracio

TRACIO dostarcza podpisane zdarzenie do Twojego endpointu przy każdej identyfikacji. Zweryfikuj nagłówek X-Tracio-Signature, a następnie działaj na płaskim payloadzie JSON. To powierzchnia push: nie musisz o nią odpytywać. Jeśli jednak potrzebujesz odczytać wizytę po fakcie, Server API odpowiada po requestId.

Żądanie

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...

Odpowiedź

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

Pobierz publiczne klucze Ed25519 platformy używane do weryfikacji dostarczeń webhooków. Ta ścieżka nie wymaga uwierzytelnienia i jest buforowana przez pięć minut. Pole kid w nagłówku podpisu wskazuje, którego klucza użyć.

Żądanie

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

Odpowiedź

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

GET/v1/visitors/{visitorId}

Odczytaj historię odwiedzającego z Server API za pomocą swojego klucza sekretnego. Dostępne od planu Pro. Okno jest ograniczane do Twojego planu, a okno, które faktycznie otrzymałeś, jest raportowane w meta. Obsługuje żądania prawa dostępu w ramach RODO.

Żądanie

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

Odpowiedź

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

Uwierzytelnianie

TRACIO używa trzech poświadczeń, po jednym na powierzchnię: klucza publicznego dla przeglądarkowego SDK, klucza sekretnego (tracio_sk_…) wysyłanego jako Authorization: Bearer do Server API oraz sekretu podpisującego HMAC do weryfikacji dostarczeń webhooków. Klucz sekretny tworzy się w panelu, jest pokazywany raz i nigdy nie może trafić do przeglądarki — Server API celowo nie zwraca nagłówków 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>

Limity szybkości

Limity obowiązują per przestrzeń robocza. Wywołania Server API są liczone oddzielnie od identyfikacji, więc odczyt własnej historii nigdy nie zużywa limitu, za który płacisz. Każda odpowiedź zawiera X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset, a przy 429 dodatkowo Retry-After. Server API nie wchodzi w skład planu Free.

Plan	Server API na sekundę	Server API na dobę	Endpointy webhook	Okno zapytań
Free	Niedostępne	Niedostępne	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	Bez limitu	100	365 days

Kody błędów

Każdy błąd zwraca tę samą kopertę: obiekt error z tekstowym kodem, czytelnym komunikatem oraz requestId nieudanego wywołania.

400Bad RequestNieprawidłowe parametry zapytania, nieobsługiwane okno lub identyfikator, który nie jest poprawnym ID odwiedzającego.

401UnauthorizedBrak lub nieprawidłowe poświadczenia — klucz publiczny (SDK), klucz sekretny (Server API) lub podpis webhook.

402Upgrade RequiredTwój plan nie obejmuje dostępu do Server API. Zaczyna się on od planu Pro.

404Not FoundNie znaleziono odwiedzającego ani sesji o tym identyfikatorze w oknie zapytań Twojego planu.

405Method Not AllowedServer API działa tylko do odczytu. Każda ścieżka odpowiada na GET i na nic więcej.

429Rate LimitedZbyt wiele żądań na sekundę lub wyczerpany limit dzienny. Sprawdź nagłówek Retry-After oraz limity swojego planu.

500Internal ErrorBłąd serwera. Ponów próbę z wykładniczym odczekiwaniem. Jeśli problem się utrzymuje, skontaktuj się ze wsparciem, podając requestId.

503Service UnavailableAPI tymczasowo nie może odpowiedzieć. Ponów próbę z wykładniczym odczekiwaniem.

Format odpowiedzi błędu

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

Zacznij budować

Uzyskaj klucz API i wykonaj pierwsze żądanie identyfikacji w mniej niż 5 minut.

Uzyskaj klucz API Pełna dokumentacja API