Server API

La Server API consente al suo backend di leggere i dati di identificazione che TRACIO ha già raccolto per il suo workspace: la cronologia di un visitatore, le singole sessioni e i contatori di velocity su finestre brevi.

Integra i Webhook invece di sostituirli:

Entrambe le superfici sono disponibili dal piano Pro in su.

URL di base

https://api.tracio.ai/v1

Si tratta di un host diverso da quello dell'endpoint del browser (edge.tracio.ai) e dalla dashboard (app.tracio.ai). Tutti e tre sono separati: il browser parla con l'edge usando la sua chiave pubblica, il suo backend parla con la Server API usando la sua chiave segreta.

Autenticazione

Ogni richiesta porta la sua chiave segreta come bearer token:

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

La Server API è solo server-to-server. Gli header CORS non vengono deliberatamente restituiti, quindi un browser non può chiamarla — è questo che tiene la sua chiave segreta fuori dal codice lato client. Non spedisca mai la chiave segreta al browser.

Ottenere una chiave segreta

La crei nella dashboard, sotto API Keys, scegliendo il tipo secret.

• La chiave completa viene mostrata una sola volta, alla creazione. Dalla nostra parte è conservato solo un hash, quindi una chiave persa non può essere recuperata — al suo posto la ruoti.
• Una chiave segreta ha la forma tracio_sk_ seguito da 43 caratteri, 53 in totale. La dashboard la elenca con i suoi primi caratteri, così può distinguere le chiavi fra loro.
• Le chiavi segrete richiedono il piano Pro o superiore; la chiave pubblica usata dall'agent nel browser è un valore separato, non segreto, di 40 caratteri.

Ruotare una chiave segreta

La rotazione emette una nuova chiave e mantiene funzionante la vecchia per 7 giorni, così può distribuirla senza interruzioni di servizio. Distribuisca la nuova chiave, verifichi che il traffico si sia spostato e lasci scadere la vecchia. Le chiavi pubbliche non sono ruotabili — non sono segreti e sono visibili nel sorgente della sua pagina per scelta progettuale.

Endpoint

Ogni rotta è un GET. Nella Server API non esistono operazioni di scrittura: legge i dati, mentre la sua configurazione risiede nella dashboard.

Una barra finale viene accettata e ignorata. Un percorso sconosciuto o un metodo errato restituisce lo stesso envelope JSON di errore di tutto il resto, mai una pagina HTML o di testo semplice.

La finestra temporale

Ogni lettura è delimitata da una finestra temporale, controllata da due parametri di query facoltativi:

• Una data nuda come to include l'intera giornata.
• Qualsiasi altra cosa viene rifiutata con 400 invalid_request e il messaggio time must be YYYY-MM-DD or RFC3339.
• Se non ne passa nessuno dei due, la finestra è l'intero periodo di conservazione del suo piano, che termina adesso.
• Una finestra che risale più indietro di quanto il suo piano consenta viene ridotta in silenzio anziché rifiutata. La finestra effettivamente usata viene sempre riportata in meta, quindi controlli meta.from e meta.to invece di dare per scontato che la sua richiesta sia stata rispettata alla lettera.

Consultare un visitatore

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

La risposta porta la cronologia aggregata e incorpora l'ultima sessione, così il caso comune richiede una richiesta invece di due:

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

Un visitatore senza dati all'interno della finestra di conservazione restituisce 404 not_found con il messaggio visitor not found in the retention window — non è un errore della sua integrazione, significa che il visitatore è nuovo oppure è uscito dalla finestra per anzianità.

Campi di verdetto

La sessione porta due verdetti, che rispondono a domande diverse — se il client fosse automatizzato e che cosa abbia concluso complessivamente il motore di rischio:

bot.score e decision.riskScore vanno entrambi da 0..100. Da Business in su, guidance li trasforma in indicazioni per singolo scenario sulla scala allow → challenge → review → deny — veda Guidance per il significato di ciascun gradino.

Elencare le sessioni di un visitatore

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

Le sessioni tornano dalla più recente:

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

Paginazione

La paginazione è basata su cursore. Non esiste un parametro page o offset: rimandi il nextCursor ricevuto come cursor e prosegua finché 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
}

Tratti il cursore come opaco — il suo contenuto è un dettaglio implementativo e può cambiare. Un cursore che è stato modificato viene rifiutato con 400 invalid_request e il messaggio malformed cursor.

Recuperare una singola sessione

La più recente:

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

Restituisce un oggetto sessione nudo — non un array e non avvolto in un envelope. Un visitatore senza sessioni nella finestra restituisce 404 not_found con no sessions for this visitor in the retention window.

Oppure tramite requestId, l'identificatore che compare anche nel payload del webhook:

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

Qui visitorId è facoltativo, ma passarlo quando lo conosce rende la ricerca nettamente più veloce.

Velocity

Velocity risponde alla domanda «quanto ha fatto ultimamente questo visitatore» — la forma del credential stuffing, del card testing e delle registrazioni di massa.

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

window accetta 1h, 24h o 7d e il valore predefinito è 24h. Qualsiasi altro valore viene rifiutato con 400 invalid_request e 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 conta i valori distinti di linkedId che ha inviato per questo dispositivo — veda Collegamento degli account. botEvents è da Business in su.

Convenzioni di risposta

Un campo assente significa «nessun dato», mai zero. I campi senza valore vengono omessi del tutto invece di essere inviati come 0, "" o null: un visitatore nuovissimo non ha matchConfidence, una visita pulita non ha antidetectScore né suspectScore. L'unica eccezione deliberata è bot.score, sempre presente anche quando vale zero. Legga i campi in modo difensivo.

Il payload dipende dal suo piano. Ogni piano con accesso all'API riceve la sessione di base — identificatori, timestamp, URL, IP, user agent, browser, sistema operativo, dispositivo, geo, rete, bot, identificazione e decisione. Pro aggiunge identification.matchType, identification.matchConfidence e bot.antidetectScore. Business ed Enterprise aggiungono geo.isp, network.asn, decision.suspectScore, identification.driftScore, reasons, behavior, guidance, deviceInfo e i campi a livello di persona (personId, reputation, linkedAccountsCount, linkedVisitorsCount). L'assenza di un campo Business su un piano Pro non è un errore.

Gli interni a livello di segnale non vengono mai restituiti, su nessun piano: i nomi dei singoli segnali, i loro pesi, le soglie dietro un verdetto, i valori grezzi dei segnali e la scomposizione dei punteggi restano dalla nostra parte. Un punteggio che può essere sottoposto a reverse engineering fino ai suoi input smette di essere utile come difesa.

Errori

Ogni errore usa un unico envelope:

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

Questo requestId non è l'identificatore della visita. Due valori diversi condividono il nome: dentro il payload di una sessione requestId è l'UUID della visita, lo stesso che recapita il webhook; dentro un envelope di errore è un identificatore di traccia di 24 caratteri, generato per ogni chiamata HTTP. L'identificatore di traccia torna anche nell'header X-Request-Id di ogni risposta, riuscita o meno. Lo includa quando contatta il supporto — è così che troviamo la sua chiamata esatta.

I controlli avvengono in un ordine fisso — chiave, poi piano, poi limiti — così una richiesta con una chiave errata segnala sempre prima la chiave, mai un problema di quota.

Due casi di 401 si leggono in modo diverso di proposito: missing Authorization: Bearer <secret key> significa che l'header non è mai arrivato, mentre invalid or revoked API key significa che è arrivato e non ha trovato corrispondenza. 402 porta Data API requires the Pro plan or higher.

Limiti di frequenza e quote

Ogni risposta autenticata porta la sua situazione corrente:

• I picchi brevi sono ammessi: il limite al secondo è un token bucket che tollera fino a tre volte la frequenza sostenuta prima di iniziare a rifiutare.
• Una richiesta rifiutata per superamento della frequenza al secondo non consuma quota giornaliera, quindi un picco non può mangiarsi il budget della giornata.
• I limiti della Server API sono conteggiati separatamente dal traffico di identificazione. Leggere la propria cronologia non consuma mai le identificazioni che sta pagando.

Prossimi passi

• Webhook — riceva ogni identificazione nel momento in cui avviene
• Collegamento degli account — colleghi l'id del suo account a un dispositivo
• Rilevamento dei bot — come viene prodotto il verdetto sui bot
• Privacy e GDPR — gestione delle richieste degli interessati