Referencia de API

API Anti-Fraude

Un SDK de navegador para identificación, webhooks firmados para eventos en tiempo real y una Server API de solo lectura para el historial. 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": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "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 envío push: no tiene que sondearla. Si necesita leer una visita a posteriori, la Server API responde por requestId.

Solicitud

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

Respuesta

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

Obtenga las claves públicas Ed25519 de la plataforma que se usan para verificar las entregas de webhook. Esta ruta no necesita autenticación y se cachea durante cinco minutos. El kid del encabezado de firma le indica qué clave usar.

Solicitud

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

Respuesta

{
  "keys": [
    {
      "kid": "k1",
      "alg": "Ed25519",
      "publicKey": "MCowBQYDK2VwAyEA9tR2v1kQ..."
    }
  ]
}

GET/v1/visitors/{visitorId}

Lea el historial de un visitante desde la Server API con su clave secreta. Disponible a partir del plan Pro. La ventana se ajusta a su plan y la ventana que realmente obtuvo se informa en meta. Da soporte a las solicitudes de derecho de acceso del RGPD.

Solicitud

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

Respuesta

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

Autenticación

TRACIO utiliza tres credenciales, una por superficie: una clave pública para el SDK de navegador, una clave secreta (tracio_sk_…) enviada como Authorization: Bearer para la Server API y un secreto de firma HMAC para verificar las entregas de webhook. La clave secreta se crea en el dashboard, se muestra una sola vez y nunca debe llegar a un navegador: la Server API no devuelve encabezados CORS de forma deliberada.

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

Límites de peticiones

Los límites son por workspace. Las llamadas a la Server API se contabilizan aparte de las identificaciones, así que leer su propio historial nunca consume la cuota que usted paga. Cada respuesta incluye X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset, más Retry-After en un 429. La Server API no forma parte del plan Free.

Plan	Server API por segundo	Server API por día	Endpoints de webhook	Ventana de consulta
Free	No incluido	No incluido	0	7 days
Pro	10 req/s	10,000	5	30 days
Business	50 req/s	100,000	20	90 days
Enterprise	200 req/s	Ilimitado	100	365 days

Códigos de error

Todos los errores devuelven el mismo envoltorio: un objeto error con un code de tipo string, un mensaje legible y el requestId de la llamada fallida.

400Bad RequestParámetros de consulta mal formados, una ventana no soportada o un identificador que no es un visitor ID válido.

401UnauthorizedCredenciales ausentes o inválidas: clave pública (SDK), clave secreta (Server API) o firma de webhook.

402Upgrade RequiredSu plan no incluye acceso a la Server API. Comienza en el plan Pro.

404Not FoundNingún visitante o sesión con ese identificador dentro de la ventana de consulta de su plan.

405Method Not AllowedLa Server API es de solo lectura. Todas las rutas responden a GET y nada más.

429Rate LimitedDemasiadas solicitudes por segundo, o la cuota diaria está agotada. 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 indicando el requestId.

503Service UnavailableLa API no puede responder temporalmente. Reintente con retroceso exponencial.

Formato de respuesta de error

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

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