Server API

Server API дозволяє вашому бекенду читати дані ідентифікації, які TRACIO вже зібрав для вашого workspace: історію відвідувача, окремі сесії та лічильники активності за коротке вікно.

Він доповнює Webhooks, а не замінює їх:

Обидві поверхні доступні з тарифу Pro і вище.

Базова URL-адреса

https://api.tracio.ai/v1

Це окремий хост — не той, що у браузерної кінцевої точки (edge.tracio.ai), і не той, що у дашборда (app.tracio.ai). Усі три різні: браузер спілкується з edge вашим публічним ключем, ваш бекенд спілкується з Server API вашим секретним ключем.

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

Кожен запит несе ваш секретний ключ як bearer-токен:

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

Server API працює лише в режимі server-to-server. Заголовки CORS навмисно не повертаються, тож браузер не може його викликати — саме це утримує ваш секретний ключ поза клієнтським кодом. Ніколи не віддавайте секретний ключ у браузер.

Як отримати секретний ключ

Створіть його в дашборді, у розділі API Keys, обравши тип secret.

• Повний ключ показується рівно один раз, під час створення. На нашому боці зберігається лише хеш, тож втрачений ключ відновити неможливо — замість цього ротуйте його.
• Секретний ключ виглядає як tracio_sk_ плюс 43 символи, разом 53. Дашборд показує його за першими кількома символами, щоб ви могли відрізняти ключі один від одного.
• Секретні ключі потребують тарифу Pro або вище; публічний ключ, який використовує браузерний агент, — це окреме несекретне значення з 40 символів.

Ротація секретного ключа

Ротація випускає новий ключ і залишає старий робочим ще 7 днів, тож ви можете викотити заміну без простою. Задеплойте новий ключ, переконайтеся, що трафік перейшов на нього, і дайте старому спливти. Публічні ключі не ротуються — вони не є секретами й за задумом видимі у вихідному коді вашої сторінки.

Кінцеві точки

Усі маршрути — GET. Операцій запису в Server API немає: він читає дані, а ваша конфігурація живе в дашборді.

Завершальна скісна риска приймається й ігнорується. Невідомий шлях або хибний метод повертають той самий JSON-конверт помилки, що й усе інше, — ніколи не HTML- і не текстову сторінку.

Часове вікно

Будь-яке читання обмежене часовим вікном, яким керують два необов’язкові параметри запиту:

• Гола дата в to включає весь цей день цілком.
• Усе інше відхиляється з 400 invalid_request і повідомленням time must be YYYY-MM-DD or RFC3339.
• Якщо ви не передали ані того, ані іншого, вікном стає повний строк зберігання вашого тарифу, що завершується зараз.
• Вікно, яке сягає в минуле далі, ніж дозволяє ваш тариф, мовчки підрізається, а не відхиляється. Фактично застосоване вікно завжди повертається в meta, тож перевіряйте meta.from і meta.to, а не вважайте, що ваш запит виконано дослівно.

Пошук відвідувача

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

Відповідь несе агреговану історію і містить у собі останню сесію, тож у типовому випадку вистачає одного запиту, а не двох:

{
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "firstSeenAt": "2026-05-02T10:11:12Z",
  "lastSeenAt": "2026-07-25T08:00:00Z",
  "visits": 42,
  "incognitoVisits": 3,
  "uniqueIps": 5,
  "uniqueCountries": 2,
  "browsers": ["Chrome"],
  "os": ["macOS"],
  "devices": ["desktop"],
  "risk": {
    "maxRiskScore": 63,
    "avgBotScore": 12.5,
    "botSessions": 7,
    "lastDecision": "real"
  },
  "network": {
    "vpnSeen": false,
    "proxySeen": false,
    "torSeen": false,
    "datacenterSeen": true,
    "lastIsp": "Deutsche Telekom"
  },
  "lastSession": {
    "requestId": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
    "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
    "accountId": "user_8842",
    "timestamp": "2026-07-25T08:00:00Z",
    "tag": "checkout",
    "url": "https://shop.example.com/checkout",
    "ip": "203.0.113.42",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "browser": { "name": "Chrome", "version": "126.0" },
    "os": { "name": "macOS", "version": "14.5" },
    "device": "desktop",
    "geo": {
      "country": "DE",
      "city": "Berlin",
      "timezone": "Europe/Berlin",
      "isp": "Deutsche Telekom"
    },
    "network": {
      "vpn": false,
      "proxy": false,
      "tor": false,
      "datacenter": false,
      "asn": 3320
    },
    "bot": { "result": "human", "score": 4.5, "antidetectScore": 2.1 },
    "identification": {
      "confidence": 0.97,
      "incognito": false,
      "matchType": "exact",
      "matchConfidence": 0.99
    },
    "decision": { "action": "real", "riskScore": 12 }
  },
  "meta": {
    "plan": "business",
    "retentionDays": 90,
    "from": "2026-04-26T00:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

Відвідувач, щодо якого немає даних усередині вікна зберігання, віддає 404 not_found з повідомленням visitor not found in the retention window — це не помилка вашої інтеграції, а ознака того, що відвідувач новий або вже вийшов за строк зберігання.

Поля вердикту

Сесія несе два вердикти, і вони відповідають на різні питання — чи був клієнт автоматизованим і до якого загального висновку дійшов рушій ризику:

bot.score і decision.riskScore обидва йдуть у шкалі 0..100. На Business і вище guidance перетворює їх на рекомендації для кожного сценарію на драбині allow → challenge → review → deny — що означає кожен щабель, див. у розділі Guidance.

Список сесій відвідувача

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y/sessions?limit=100&minRiskScore=50"

Сесії повертаються починаючи з найсвіжіших:

{
  "items": [
    {
      "requestId": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
      "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
      "timestamp": "2026-07-25T08:00:00Z"
    }
  ],
  "nextCursor": "MTcyMTg5NDQwMDAwMDphYmMxMjM",
  "hasMore": true,
  "meta": {
    "plan": "business",
    "retentionDays": 90,
    "from": "2026-04-26T00:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

Пагінація

Посторінкова вибірка побудована на курсорах. Параметрів page або offset немає: передайте отриманий nextCursor назад як cursor і продовжуйте, доки hasMore дорівнює true.

async function allSessions(visitorId: string, secretKey: string) {
  const sessions = []
  let cursor: string | undefined

  do {
    const url = new URL(`https://api.tracio.ai/v1/visitors/${visitorId}/sessions`)
    url.searchParams.set("limit", "500")
    if (cursor) url.searchParams.set("cursor", cursor)

    const res = await fetch(url, { headers: { Authorization: `Bearer ${secretKey}` } })
    if (!res.ok) throw new Error(`Server API: ${res.status}`)

    const page = await res.json()
    sessions.push(...page.items)
    cursor = page.nextCursor
  } while (cursor)

  return sessions
}

Вважайте курсор непрозорим — його вміст є деталлю реалізації і може змінитися. Відредагований курсор відхиляється з 400 invalid_request і повідомленням malformed cursor.

Отримання однієї сесії

Найсвіжіша:

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y/sessions/latest"

Повертається голий об’єкт сесії — не масив і не загорнутий у конверт. Відвідувач без сесій у вікні віддає 404 not_found з повідомленням no sessions for this visitor in the retention window.

Або за requestId — ідентифікатором, який трапляється й у payload вебхука:

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/sessions/9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31?visitorId=X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

visitorId тут необов’язковий, але якщо ви його знаєте, передача помітно прискорює пошук.

Velocity

Velocity відповідає на питання «скільки цей відвідувач устиг наробити останнім часом» — саме так виглядають перебір облікових даних, тестування карток і масові реєстрації.

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y/velocity?window=1h"

window приймає 1h, 24h або 7d, за замовчуванням — 24h. Будь-яке інше значення відхиляється з 400 invalid_request і повідомленням window must be one of: 1h, 24h, 7d.

{
  "window": "1h",
  "events": 37,
  "uniqueIps": 9,
  "uniqueCountries": 3,
  "uniqueAccounts": 12,
  "botEvents": 4,
  "meta": {
    "plan": "business",
    "retentionDays": 90,
    "from": "2026-07-25T11:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

uniqueAccounts рахує різні значення linkedId, які ви надіслали для цього пристрою, — див. Зв’язування акаунтів. botEvents доступне на Business і вище.

Домовленості щодо відповідей

Відсутнє поле означає «немає даних», а не нуль. Поля без значення опускаються цілком, а не надсилаються як 0, "" чи null: у зовсім нового відвідувача немає matchConfidence, у чистого візиту немає antidetectScore та suspectScore. Єдиний навмисний виняток — bot.score: воно присутнє завжди, навіть коли дорівнює нулю. Читайте поля захисно.

Payload залежить від вашого тарифу. Будь-який тариф із доступом до API отримує базову сесію — ідентифікатори, таймстамп, URL, IP, user agent, браузер, ОС, пристрій, гео, мережа, бот, ідентифікація та рішення. Pro додає identification.matchType, identification.matchConfidence і bot.antidetectScore. Business та Enterprise додають geo.isp, network.asn, decision.suspectScore, identification.driftScore, reasons, behavior, guidance, deviceInfo і поля рівня персони (personId, reputation, linkedAccountsCount, linkedVisitorsCount). Відсутність поля рівня Business на тарифі Pro — не помилка.

Внутрішнє на рівні сигналів не повертається ніколи, на жодному тарифі: імена окремих сигналів, їхні ваги, пороги за вердиктом, сирі значення сигналів і розкладка оцінок залишаються на нашому боці. Оцінка, яку можна зворотною розробкою звести до її вхідних даних, перестає бути захистом.

Помилки

Будь-який збій використовує один конверт:

{
  "error": {
    "code": "unauthorized",
    "message": "missing Authorization: Bearer <secret key>",
    "requestId": "8f14e45fceea167a5a36dedd"
  }
}

Цей requestId — не ідентифікатор візиту. Ім’я ділять два різні значення: всередині payload сесії requestId — це UUID візиту, той самий, який доставляє вебхук; у конверті помилки це 24-символьний ідентифікатор трасування, що випускається на кожен HTTP-виклик. Ідентифікатор трасування повертається ще й у заголовку X-Request-Id на кожній відповіді, успішній чи ні. Додайте його, коли звертаєтесь до підтримки, — саме за ним ми знаходимо ваш конкретний виклик.

Перевірки йдуть у фіксованому порядку — ключ, потім тариф, потім ліміти, — тож запит із поганим ключем завжди повідомляє спершу про ключ, а не про проблему з квотою.

Два випадки 401 навмисно читаються по-різному: missing Authorization: Bearer <secret key> означає, що заголовок узагалі не надійшов, а invalid or revoked API key — що він надійшов і не збігся. 402 несе Data API requires the Pro plan or higher.

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

Кожна автентифікована відповідь несе ваше поточне становище:

• Короткі сплески дозволені: посекундний ліміт — це token bucket, який терпить до трикратного перевищення сталої швидкості, перш ніж починає відмовляти.
• Запит, відхилений за перевищення посекундної швидкості, не витрачає денну квоту, тож сплеск не може з’їсти бюджет дня.
• Ліміти Server API рахуються окремо від трафіку ідентифікації. Читання власної історії ніколи не витрачає ідентифікації, за які ви платите.

Наступні кроки

• Webhooks — отримуйте кожну ідентифікацію в момент, коли вона відбувається
• Зв’язування акаунтів — прив’яжіть власний ідентифікатор акаунта до пристрою
• Виявлення ботів — як формується вердикт щодо ботів
• Приватність і GDPR — обробка запитів суб’єктів даних