Přejít na obsah

Referenční příručka API

Antifraudové API

Prohlížečový SDK pro identifikaci, podepsané webhooky pro události v reálném čase a Server API jen pro čtení pro historii. Vše, co potřebujete k zastavení podvodů na úrovni zařízení.

Získat API klíčAPI Playground

Endpointy

SDK@tracio/sdk

Identifikujte návštěvníka v prohlížeči pomocí klientského SDK. Vrací stabilní ID návštěvníka a verdikt o botovi bez zpáteční komunikace se serverem. Veřejný klíč je bezpečné dodávat v kódu na straně klienta.

Požadavek

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

Odpověď

{
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "bot": {
    "detected": false,
    "confidence": 2,
    "reasons": []
  }
}
POST/webhook/tracio

TRACIO doručí podepsanou událost na váš endpoint při každé identifikaci. Ověřte hlavičku X-Tracio-Signature a poté zpracujte plochý JSON payload. Toto je push plocha: nemusíte se na ni dotazovat. Pokud přesto potřebujete přečíst návštěvu dodatečně, Server API odpovídá podle requestId.

Požadavek

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

Odpověď

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

Získejte veřejné klíče Ed25519 platformy používané k ověření doručení webhooků. Tato cesta nevyžaduje autentizaci a je pět minut kešovaná. Pole kid v hlavičce podpisu říká, který klíč použít.

Požadavek

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

Odpověď

{
  "keys": [
    {
      "kid": "k1",
      "alg": "Ed25519",
      "publicKey": "MCowBQYDK2VwAyEA9tR2v1kQ..."
    }
  ]
}
GET/v1/visitors/{visitorId}

Přečtěte historii návštěvníka ze Server API pomocí svého tajného klíče. Dostupné od plánu Pro. Okno je omezeno vaším plánem a to, které jste skutečně dostali, se hlásí zpět v meta. Podporuje požadavky na přístup k datům podle GDPR.

Požadavek

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

Odpověď

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

Autentizace

TRACIO používá tři přihlašovací údaje, jeden pro každou plochu: veřejný klíč pro prohlížečový SDK, tajný klíč (tracio_sk_…) posílaný jako Authorization: Bearer pro Server API a HMAC podpisový tajný klíč k ověření doručení webhooků. Tajný klíč se vytváří v dashboardu, zobrazí se jen jednou a nikdy se nesmí dostat do prohlížeče — Server API záměrně nevrací žádné CORS hlavičky.

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

Omezení počtu požadavků

Limity jsou na workspace. Volání Server API se počítají odděleně od identifikací, takže čtení vlastní historie nikdy nespotřebuje kvótu, kterou platíte. Každá odpověď nese X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset a při 429 navíc Retry-After. Server API není součástí plánu Free.

PlánFrekvence Server APIServer API za denWebhookové endpointyOkno dotazů
FreeNení součástíNení součástí07 days
Pro10 req/s10,000530 days
Business50 req/s100,0002090 days
Enterprise200 req/sNeomezeně100365 days

Chybové kódy

Každá chyba vrací stejnou obálku: objekt error s řetězcovým kódem code, čitelnou zprávou message a s requestId neúspěšného volání.

400Bad RequestChybně formátované parametry dotazu, nepodporované okno nebo identifikátor, který není platné ID návštěvníka.
401UnauthorizedChybějící nebo neplatné přihlašovací údaje — veřejný klíč (SDK), tajný klíč (Server API) nebo podpis webhooku.
402Upgrade RequiredVáš plán nezahrnuje přístup k Server API. Začíná plánem Pro.
404Not FoundVe vašem plánovém okně dotazů neexistuje návštěvník ani relace s tímto identifikátorem.
405Method Not AllowedServer API je jen pro čtení. Každá cesta odpovídá na GET a na nic jiného.
429Rate LimitedPříliš mnoho požadavků za sekundu nebo vyčerpaná denní kvóta. Zkontrolujte hlavičku Retry-After a limity svého plánu.
500Internal ErrorChyba serveru. Opakujte s exponenciálním odstupem. Pokud přetrvává, kontaktujte podporu s requestId.
503Service UnavailableAPI dočasně nemůže odpovědět. Opakujte s exponenciálním odstupem.

Formát chybové odpovědi

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

Začněte stavět

Získejte svůj API klíč a proveďte první požadavek na identifikaci za méně než 5 minut.

Získat API klíčKompletní dokumentace API