Vada al contenuto

Riferimento API

API antifrode

Un SDK browser per l'identificazione, webhook firmati per gli eventi in tempo reale e una Server API di sola lettura per lo storico. Tutto ciò che serve per fermare le frodi a livello di dispositivo.

Ottenga la chiave APIAPI Playground

Endpoint

SDK@tracio/sdk

Identifica un visitatore nel browser con il client SDK. Restituisce un ID visitatore stabile e un verdetto sui bot senza round-trip verso il server. La chiave pubblica può essere inclusa in sicurezza nel codice lato client.

Richiesta

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

Risposta

{
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "bot": {
    "detected": false,
    "confidence": 2,
    "reasons": []
  }
}
POST/webhook/tracio

TRACIO invia un evento firmato al suo endpoint a ogni identificazione. Verifichi l'header X-Tracio-Signature, poi agisca sul payload JSON piatto. Questa è la superficie push: non deve interrogarla con il polling. Se le serve leggere una visita a posteriori, la Server API risponde per requestId.

Richiesta

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

Risposta

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

Recupera le chiavi pubbliche Ed25519 della piattaforma usate per verificare le consegne dei webhook. Questa route non richiede autenticazione ed è in cache per cinque minuti. Il kid nell'header della firma indica quale chiave usare.

Richiesta

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

Risposta

{
  "keys": [
    {
      "kid": "k1",
      "alg": "Ed25519",
      "publicKey": "MCowBQYDK2VwAyEA9tR2v1kQ..."
    }
  ]
}
GET/v1/visitors/{visitorId}

Legge la cronologia di un visitatore dalla Server API con la sua secret key. Disponibile dal piano Pro. La finestra è limitata al suo piano e quella effettivamente ottenuta viene riportata in meta. Supporta le richieste di diritto di accesso previste dal GDPR.

Richiesta

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

Risposta

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

Autenticazione

TRACIO utilizza tre credenziali, una per superficie: una chiave pubblica per l'SDK browser, una secret key (tracio_sk_…) inviata come Authorization: Bearer per la Server API e un signing secret HMAC per verificare le consegne dei webhook. La secret key viene creata nella dashboard, mostrata una sola volta e non deve mai raggiungere un browser: la Server API non restituisce deliberatamente alcun header 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>

Limiti di frequenza

I limiti sono per workspace. Le chiamate alla Server API sono conteggiate separatamente dalle identificazioni, così leggere la propria cronologia non consuma mai la quota che paga. Ogni risposta include X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset, più Retry-After in caso di 429. La Server API non fa parte del piano Free.

PianoFrequenza Server APIServer API al giornoEndpoint webhookFinestra di query
FreeNon inclusoNon incluso07 days
Pro10 req/s10,000530 days
Business50 req/s100,0002090 days
Enterprise200 req/sIllimitato100365 days

Codici di errore

Ogni errore restituisce lo stesso envelope: un oggetto error con un code testuale, un message leggibile e il requestId della chiamata fallita.

400Bad RequestParametri di query malformati, una finestra non supportata o un identificatore che non è un ID visitatore valido.
401UnauthorizedCredenziali mancanti o non valide: chiave pubblica (SDK), secret key (Server API) o firma del webhook.
402Upgrade RequiredIl suo piano non include l'accesso alla Server API. Parte dal piano Pro.
404Not FoundNessun visitatore o sessione con quell'identificatore nella finestra di query del suo piano.
405Method Not AllowedLa Server API è di sola lettura. Ogni route risponde a GET e a nient'altro.
429Rate LimitedTroppe richieste al secondo, oppure la quota giornaliera è esaurita. Controlli l'header Retry-After e i limiti del suo piano.
500Internal ErrorErrore del server. Riprovi con backoff esponenziale. Se persiste, contatti l'assistenza indicando il requestId.
503Service UnavailableL'API non è temporaneamente in grado di rispondere. Riprovi con backoff esponenziale.

Formato della risposta di errore

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

Inizi a sviluppare

Ottenga la sua chiave API ed effettui la prima richiesta di identificazione in meno di 5 minuti.

Ottenga la chiave APIDocumentazione API completa