Referencia de API

API Anti-Fraude

Un SDK de navegador para identificación, webhooks firmados para eventos en tiempo real y una API de gestión de workspace. Todo lo que necesita para detener el fraude a nivel de dispositivo.

Obtener clave de API API Playground

Endpoints

SDK@tracio/sdk

Identifique a un visitante en el navegador con el SDK de cliente. Devuelve un visitor ID estable y un veredicto de bot sin ida y vuelta al servidor. La clave pública es segura para incluir en el código del lado del cliente.

Solicitud

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

Respuesta

{
  "visitorId": "X7fh2Hg9LkMn3pQr",
  "bot": {
    "detected": false,
    "confidence": 2,
    "reasons": []
  }
}

POST/webhook/tracio

TRACIO entrega un evento firmado a su endpoint en cada identificación. Verifique el encabezado X-Tracio-Signature y luego actúe sobre el payload JSON plano. Esta es la superficie de eventos del lado del servidor: no hay lectura REST de sondeo por requestId.

Solicitud

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

Respuesta

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

Registre un endpoint de webhook a través de la API de gestión de workspace. Se autentica con el JWT de su sesión de dashboard (Clerk) y se valida contra su rol en el workspace. El secreto de firma se devuelve una única vez, en el momento de la creación.

Solicitud

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

Respuesta

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

Consulte el historial almacenado de un visitante a través de la API de gestión de workspace, autenticándose con el JWT de su sesión de dashboard (Clerk). Da soporte a las solicitudes de derecho de acceso del RGPD.

Solicitud

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

Respuesta

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

Autenticación

TRACIO utiliza tres credenciales, una por superficie: una clave pública para el SDK de navegador, el JWT de su sesión de dashboard (Clerk) para la API de gestión de workspace y un secreto de firma HMAC para verificar las entregas de webhook. No existe un secreto de API independiente.

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

Límites de peticiones

Los límites son por workspace. Las respuestas de la API de gestión incluyen los encabezados X-RateLimit-Limit, X-RateLimit-Remaining y Retry-After.

Plan	Identificaciones	Eventos de webhook	API de gestión	Consultas de visitante
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

Códigos de error

Todos los errores devuelven un cuerpo JSON con los campos code, message y details.

400Bad RequestCuerpo de solicitud mal formado o campos obligatorios ausentes.

401UnauthorizedCredenciales ausentes o inválidas: clave pública (SDK), JWT de Clerk (API de gestión) o firma de webhook.

403ForbiddenSu rol en el workspace (RBAC) no tiene permiso para esta operación.

404Not FoundVisitor ID o webhook no encontrado en su workspace.

429Rate LimitedDemasiadas solicitudes. Revise el encabezado Retry-After y los límites de su plan.

500Internal ErrorError del servidor. Reintente con retroceso exponencial. Si persiste, contacte con soporte.

Formato de respuesta de error

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

Empiece a construir

Obtenga su clave de API y realice su primera solicitud de identificación en menos de 5 minutos.

Obtener clave de API Documentación completa de la API