Довідник API

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

Браузерний SDK для ідентифікації, підписані webhooks для подій у реальному часі та 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": "X7fh2Hg9LkMn3pQr",
  "bot": {
    "detected": false,
    "confidence": 2,
    "reasons": []
  }
}

POST/webhook/tracio

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

Запит

POST /webhook/tracio HTTP/1.1
Host: your-server.com
Content-Type: application/json
X-Tracio-Signature: t=1710432000,v1=5257a869e7ecebed...

Відповідь

{
  "requestId": "1710432000_abc123",
  "visitorId": "X7fh2Hg9LkMn3pQr",
  "bot": { "result": "human", "type": "", "score": 0.02 },
  "identification": { "confidence": 0.95, "visitType": "returning" },
  "network": { "vpn": false, "proxy": false, "tor": false, "datacenter": false },
  "decision": { "action": "allow", "riskScore": 4 }
}

POST/api/v1/workspaces/{workspaceId}/webhooks

Зареєструйте webhook-ендпоінт через API керування робочим простором. Автентифікація через JWT сесії дашборда (Clerk) і перевірка за вашою роллю в робочому просторі. Секрет підпису повертається один раз під час створення.

Запит

curl -X POST \
  https://app.tracio.ai/api/v1/workspaces/{workspaceId}/webhooks \
  -H "Authorization: Bearer <clerk-session-jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-server.com/webhook/tracio", "events": [] }'

Відповідь

{
  "ok": true,
  "data": {
    "id": "wh_abc123",
    "url": "https://your-server.com/webhook/tracio",
    "events": [],
    "signingSecret": "f3a9…<hex>",
    "status": "active",
    "createdAt": "2024-03-12T16:00:00Z"
  }
}

GET/api/v1/workspaces/{workspaceId}/visitors/{visitorId}

Перегляньте збережену історію відвідувача через API керування робочим простором з автентифікацією через JWT сесії дашборда (Clerk). Забезпечує запити на право доступу за GDPR.

Запит

curl \
  https://app.tracio.ai/api/v1/workspaces/{workspaceId}/visitors/X7fh2Hg9LkMn3pQr \
  -H "Authorization: Bearer <clerk-session-jwt>"

Відповідь

{
  "ok": true,
  "data": {
    "visitorId": "X7fh2Hg9LkMn3pQr",
    "firstSeenAt": "2024-03-01T08:11:00Z",
    "lastSeenAt": "2024-03-16T14:22:01Z",
    "visits": 12
  }
}

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

TRACIO використовує три облікові дані, по одному на поверхню: публічний ключ для браузерного SDK, JWT сесії дашборда (Clerk) для API керування робочим простором і HMAC-секрет підпису для перевірки доставок webhook. Окремого секрету API немає.

# Client SDK — public key (safe to ship in the browser)
Tracio.init({ publicKey: '5ca175fc...' })
# Workspace management API — dashboard session (Clerk) JWT,
# additionally checked against your workspace role (RBAC)
Authorization: Bearer <clerk-session-jwt>
# Webhook verification — HMAC-SHA256 over "<t>.<rawBody>"
X-Tracio-Signature: t=<unix>,v1=<hmac_sha256_hex>

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

Ліміти діють на робочий простір. Відповіді Management API містять заголовки X-RateLimit-Limit, X-RateLimit-Remaining і Retry-After.

Тариф	Ідентифікації	Webhook-події	Management API	Перегляди відвідувачів
Free	100/day	100/day	50/day	100/day
Pro	1,000/min	1,000/min	500/min	1,000/min
Enterprise	10,000/min	10,000/min	5,000/min	10,000/min

Коди помилок

Усі помилки повертають JSON-тіло з полями code, message і details.

400Bad RequestНекоректне тіло запиту або відсутні обов’язкові поля.

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

403ForbiddenВашій ролі в робочому просторі (RBAC) бракує дозволу на цю операцію.

404Not FoundID відвідувача або webhook не знайдено у вашому робочому просторі.

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

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

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

{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded",
    "details": "1000 requests per minute limit reached for this workspace",
    "retryAfter": 12
  }
}

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

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

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