Справочник по API

API для борьбы с фродом

Браузерный SDK для идентификации, подписанные вебхуки для событий в реальном времени и 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-пейлоада. Это серверная поверхность событий — REST-чтения с опросом по requestId нет.

Запрос

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

Зарегистрируйте эндпоинт вебхука через 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-секрет для проверки доставок вебхуков. Отдельного секрета 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>

Ограничения частоты

Лимиты действуют на рабочее пространство. Ответы API управления включают заголовки X-RateLimit-Limit, X-RateLimit-Remaining и Retry-After.

План	Идентификаций	События вебхуков	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), JWT Clerk (API управления) или подпись вебхука.

403ForbiddenВаша роль в рабочем пространстве (RBAC) не имеет прав на эту операцию.

404Not FoundID посетителя или вебхук не найдены в вашем рабочем пространстве.

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