Vada al contenuto

Riferimento API

API antifrode

Un SDK browser per l'identificazione, webhook firmati per gli eventi in tempo reale e un'API di gestione del workspace. 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": "X7fh2Hg9LkMn3pQr",
  "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 degli eventi lato server: non esiste una lettura REST tramite poll-by-requestId.

Richiesta

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

Risposta

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

Registra un endpoint webhook tramite l'API di gestione del workspace. Autenticato con il JWT della sessione dashboard (Clerk) e verificato rispetto al suo ruolo nel workspace. Il signing secret viene restituito una sola volta, alla creazione.

Richiesta

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": [] }'

Risposta

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

Consulta la cronologia archiviata di un visitatore tramite l'API di gestione del workspace, autenticata con il JWT della sessione dashboard (Clerk). Supporta le richieste di diritto di accesso previste dal GDPR.

Richiesta

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

Risposta

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

Autenticazione

TRACIO utilizza tre credenziali, una per superficie: una chiave pubblica per l'SDK browser, il JWT della sessione dashboard (Clerk) per l'API di gestione del workspace e un signing secret HMAC per verificare le consegne dei webhook. Non esiste un API secret autonomo.

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

Limiti di frequenza

I limiti sono per workspace. Le risposte dell'API di gestione includono gli header X-RateLimit-Limit, X-RateLimit-Remaining e Retry-After.

PianoIdentificazioniEventi webhookManagement APIConsultazioni visitatori
Free100/day100/day50/day100/day
Pro1,000/min1,000/min500/min1,000/min
Enterprise10,000/min10,000/min5,000/min10,000/min

Codici di errore

Tutti gli errori restituiscono un corpo JSON con i campi code, message e details.

400Bad RequestCorpo della richiesta malformato o campi obbligatori mancanti.
401UnauthorizedCredenziali mancanti o non valide: chiave pubblica (SDK), JWT Clerk (management API) o firma del webhook.
403ForbiddenIl suo ruolo nel workspace (RBAC) non dispone dell'autorizzazione per questa operazione.
404Not FoundID visitatore o webhook non trovato nel suo workspace.
429Rate LimitedTroppe richieste. Controlli l'header Retry-After e i limiti del suo piano.
500Internal ErrorErrore del server. Riprovate con backoff esponenziale. Se persiste, contattate l'assistenza.

Formato della risposta di errore

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

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