Довідник API

API для боротьби з шахрайством

Браузерний SDK для ідентифікації, підписані webhooks для подій у реальному часі та Server API лише для читання — для історії. Усе, що потрібно, щоб зупиняти шахрайство на рівні пристрою.

Отримати ключ API API Playground

Ендпоінти

SDK@tracio/sdk

Ідентифікуйте відвідувача в браузері за допомогою клієнтського SDK. Повертає стабільний ID відвідувача та вердикт щодо бота без звернення до сервера. Публічний ключ безпечно постачати у клієнтському коді.

Запит

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

Відповідь

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

POST/webhook/tracio

TRACIO доставляє підписану подію на ваш ендпоінт під час кожної ідентифікації. Перевірте заголовок X-Tracio-Signature, а потім дійте на основі плаского JSON-payload. Це push-поверхня: опитувати її не потрібно. Якщо ж візит треба прочитати постфактум, Server API відповідає за requestId.

Запит

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

Відповідь

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

Отримайте публічні ключі Ed25519 платформи, якими перевіряються доставки webhook. Цей маршрут не потребує автентифікації і кешується на п’ять хвилин. Поле kid у заголовку підпису вказує, який ключ використати.

Запит

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

Відповідь

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

GET/v1/visitors/{visitorId}

Читайте історію відвідувача із Server API за допомогою секретного ключа. Доступно з тарифу Pro. Вікно обмежується вашим тарифом, а фактично видане вікно повертається в meta. Забезпечує запити на право доступу за GDPR.

Запит

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

Відповідь

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

Автентифікація

TRACIO використовує три облікові дані, по одному на поверхню: публічний ключ для браузерного SDK, секретний ключ (tracio_sk_…), що передається як Authorization: Bearer, для Server API і HMAC-секрет підпису для перевірки доставок webhook. Секретний ключ створюється в дашборді, показується один раз і ніколи не повинен потрапляти в браузер — Server API навмисно не повертає 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>

Ліміти частоти

Ліміти діють на робочий простір. Виклики Server API рахуються окремо від ідентифікацій, тож читання власної історії ніколи не витрачає оплачену квоту. Кожна відповідь містить X-RateLimit-Limit, X-RateLimit-Remaining і X-RateLimit-Reset, а при 429 — ще й Retry-After. До тарифу Free Server API не входить.

Тариф	Частота Server API	Server API на день	Webhook-ендпоінти	Вікно запиту
Free	Не входить	Не входить	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	Без ліміту	100	365 days

Коди помилок

Кожна помилка повертається в одній і тій самій обгортці: об’єкт error зі строковим кодом, зрозумілим людині повідомленням і requestId невдалого виклику.

400Bad RequestНекоректні параметри запиту, непідтримуване вікно або ідентифікатор, який не є коректним ID відвідувача.

401UnauthorizedВідсутні або недійсні облікові дані — публічний ключ (SDK), секретний ключ (Server API) або підпис webhook.

402Upgrade RequiredВаш тариф не включає доступ до Server API. Він починається з тарифу Pro.

404Not FoundВідвідувача або сесію з таким ідентифікатором не знайдено у вікні запиту вашого тарифу.

405Method Not AllowedServer API працює лише на читання. Кожен маршрут відповідає на GET і ні на що інше.

429Rate LimitedЗабагато запитів за секунду або вичерпано денну квоту. Перевірте заголовок Retry-After і ліміти вашого тарифу.

500Internal ErrorПомилка сервера. Повторіть із експоненційною затримкою. Якщо помилка стійка, зверніться до підтримки з requestId.

503Service UnavailableAPI тимчасово не може відповісти. Повторіть із експоненційною затримкою.

Формат відповіді про помилку

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

Почніть створювати

Отримайте ключ API і зробіть перший запит на ідентифікацію менш ніж за 5 хвилин.

Отримати ключ API Повна документація API