Sus datos, allí donde toma la decisión
Cada identificación puede llegar a sus sistemas de dos maneras: enviada a su servidor en el momento en que ocurre, o solicitada por usted en el segundo exacto en que decide. Los dos canales llevan los mismos números — y eso lo garantiza un test, no una promesa.
Push o pull
Los webhooks le envían los eventos según ocurren. La Data API le permite preguntar en el momento en que necesita una respuesta. La mayoría de los equipos usa las dos: webhooks para registrar y reaccionar, la Data API para comprobar en línea.
Webhooks — push, en tiempo real
Hacemos POST de un evento JSON firmado a su endpoint en el momento en que algo ocurre: se identifica a un visitante, se marca un robo de cuenta, empieza un ataque de bots. Nada que consultar en bucle, nada que programar.
Ideal para: registrar cada visita, reaccionar ante ataques, alimentar su almacén de datos o su SIEM.
Latencia de entrega p50 de 44–140 ms, del evento a su endpoint.
Data API — pull, bajo demanda
Una API privada de servidor a servidor. Su backend se autentica con una clave secreta y lee exactamente lo que sabemos de un visitante en el segundo en que lo decide — normalmente dentro de un manejador de inicio de sesión o de pago.
Ideal para: una comprobación en línea antes de cobrar una tarjeta, aprobar un registro o desbloquear una cuenta.
Disponible a partir del plan Pro.
Cuatro tipos de evento, un solo sobre
Cada entrega llega en el mismo sobre, con el tipo de evento en el cuerpo y en la cabecera X-Tracio-Event-Type — de modo que un único manejador puede enrutar los cuatro.
Visitante identificado
El evento central: se ha puntuado una visita. Lleva el ID de visitante, el navegador y el sistema operativo, la geolocalización y la red, el veredicto de bot y la decisión de riesgo. Se entrega por fases — un evento primario al cargar la página y después una fase tardía o de corrección cuando una evidencia más lenta cambia el veredicto. Correlacione las fases por requestId.
identificationRobo de cuenta
El detector de robo de cuentas se disparó en una visita: el dispositivo detrás de una cuenta conocida ya no se parece al dispositivo que es su dueño. Llega como evento propio, con el contexto de la cuenta adjunto, en lugar de esconderse dentro de un cuerpo de identificación.
account_takeoverAtaque de bots
Una oleada de tráfico automatizado en su espacio de trabajo. Este no tiene una visita detrás: es una alerta a nivel de espacio de trabajo, así que los bloques de visita sencillamente faltan en el cuerpo en lugar de llegar como cascarones vacíos con puntuaciones a cero.
attack_detectedCambio de reputación
Un perfil se movió entre bandas de reputación. El mismo sobre que la alerta de ataque — un evento a nivel de perfil, sin visita asociada, que lleva la banda nueva y la anterior.
reputation_changedUna entrega, recortada
Este es el cuerpo base. Pro añade la velocidad de visitas; Business añade códigos de motivo del veredicto, señales de comportamiento, recomendaciones y datos de dispositivo entre navegadores a esta misma forma — aparecen bloques nuevos, las rutas existentes nunca se mueven.
{ "version": 2, "event": "identification", "eventId": "req_8f21c4:primary", "requestId": "req_8f21c4", "phase": "primary", "visitorId": "3f9a1b2c4d5e6f70", "timestamp": "2026-07-30T12:00:00Z", "geo": { "country": "DE", "city": "Berlin", "timezone": "Europe/Berlin" }, "network": { "vpn": true, "proxy": false, "tor": false, "datacenter": false }, "bot": { "result": "human", "score": 12 }, "identification": { "confidence": 0.97, "incognito": false }, "decision": { "action": "suspicious", "riskScore": 65.9 }}Cada petición lleva dos firmas
X-Tracio-Signature es un HMAC-SHA256 sobre la marca de tiempo de la firma unida al cuerpo bruto de la petición, con la clave de su webhook — demuestra que quien envía conoce el secreto que ambos comparten. X-Tracio-Signature-Ed25519 es la firma de la plataforma: se verifica con una clave pública que se obtiene de un endpoint conocido, así que no hay nada secreto que guardar de su lado. La marca de tiempo forma parte del contenido firmado, y eso es lo que vuelve inservible una captura antigua para reproducirla.
Verifique contra los bytes brutos de la petición: volver a serializar el JSON cambia los bytes y la firma dejará de coincidir. Los reintentos llevan el mismo X-Tracio-Event-Id, así que deduplique por él.
Cabeceras en cada entrega
X-Tracio-Signature: t=1753444800,v1=5257a869e7ecebed...X-Tracio-Signature-Ed25519: t=1753444800,kid=k1,v1=0Zx0M0n8...X-Tracio-Event-Type: identificationX-Tracio-Event-Id: req_8f21c4:primaryX-Tracio-Delivery-Attempt: 1X-Tracio-Payload-Version: 2Construido para no perder eventos
La entrega corre sobre una flota dedicada, y la fuente de verdad es la cola, no la memoria de un proceso. Eso es lo que hace real el «al menos una vez»: si un nodo de entrega muere a mitad de vuelo, el evento sigue en la cola y otro nodo lo recoge.
Reintentos a la medida de caídas reales
5 s, 30 s, 2 min, 10 min, 30 min, 2 h, 6 h. Los primeros reintentos caen dentro del primer minuto, así que un reinicio breve de su servicio no le cuesta nada. Cada pausa se elige al azar entre la mitad del valor indicado y el valor completo, para que los reintentos no vuelvan como una única descarga después de una caída.
Desactivación automática que no se dispara por error
Un webhook solo se apaga cuando los fallos alcanzan el umbral y además llevan al menos 15 minutos seguidos — una ráfaga de entregas encoladas durante un reinicio no matará la integración. Un 410 Gone lo desactiva de inmediato. El panel muestra el motivo, el código de respuesta y un botón para reactivarlo.
Rotación de secretos sin hueco
Tras una rotación, los dos secretos siguen siendo válidos durante 24 horas y la cabecera lleva ambas firmas, así que basta con que coincida una. Usted actualiza su configuración dentro de la ventana en lugar de correr contra un corte; «Revocar ahora» acorta la ventana cuando necesita que desaparezca ya.
Un registro de entregas que se puede leer
Cada intento — código de respuesta, duración, texto del error — es visible por webhook en el panel, junto a una acción de prueba que envía a su endpoint una carga de ejemplo firmada, para que pueda confirmar su verificador antes de salir a producción.
Pregunte en el momento en que decide
Una API privada de servidor a servidor en api.tracio.ai. Su backend se autentica con una clave secreta y lee sus propios datos. Deliberadamente no envía cabeceras CORS: una clave secreta da acceso a todo lo de su espacio de trabajo y nunca debe llegar a un navegador. Disponible a partir del plan Pro.
| Método | Ruta | Devuelve |
|---|---|---|
| GET | /v1/visitors/{visitorId} | Resumen del visitante: primera y última vez visto, número de visitas, IPs y países únicos, navegadores y dispositivos, historial de riesgo — más su sesión más reciente. |
| GET | /v1/visitors/{visitorId}/sessions | Lista de sesiones con paginación por cursor y filtros por rango de fechas, resultado de bot y puntuación de riesgo mínima. |
| GET | /v1/visitors/{visitorId}/sessions/latest | La sesión más reciente como un único objeto, sin envoltorio de lista. |
| GET | /v1/sessions/{requestId} | Una sesión concreta. Pase visitorId junto a ella y la búsqueda irá por el índice de visitantes en lugar de por todo su historial. |
| GET | /v1/visitors/{visitorId}/velocity | Actividad en una ventana — 1h, 24h o 7d: cuántas visitas, desde cuántas IPs, desde cuántos países, bajo cuántas cuentas. |
Comprobar un visitante al pagar
La llamada típica: dentro de su manejador de pagos, antes de autorizar la tarjeta. Una petición, una respuesta, y el bloque meta le informa de la ventana que realmente obtuvo — si pide seis meses y su plan retiene 30 días, devuelve 30 días y lo dice.
Petición
# Inside your checkout handler, before you authorize the cardcurl -s -H "Authorization: Bearer $TRACIO_SECRET_KEY" \ "https://api.tracio.ai/v1/visitors/3f9a1b2c/velocity?window=24h"Respuesta
{ "window": "24h", "events": 128, "uniqueIps": 4, "uniqueCountries": 2, "uniqueAccounts": 1, "meta": { "plan": "business", "retentionDays": 30 }}Los mismos números en todas partes
Una visita que puntúa 65,9 en su panel puntúa 65,9 en la Data API y 65,9 en el cuerpo del webhook. Dos representaciones independientes podrían separarse con el tiempo — las escalas son la vía clásica, un canal le da 0,93 donde el otro dice 93 — así que un test de paridad construye una sola visita, la representa por los dos canales y compara los campos públicos sobre el JSON bruto. La coincidencia está impuesta, no afirmada.
Consejo, no solo números
Las puntuaciones le dicen lo que vimos. Las recomendaciones le dicen qué hacer al respecto, para las cuatro decisiones que de verdad cuestan dinero — calculadas por reglas versionadas, con el razonamiento adjunto.
¿Acepto el pago?
Pondera el riesgo, la reputación de fraude y el veredicto de bot antes de que autorice una tarjeta.
¿Acepto el registro?
Detecta la cuenta desechable antes de que exista — aquí pesan más las multicuentas y la reputación.
¿Le dejo entrar?
Se endurece de forma automática cuando el detector de robo de cuentas se ha disparado en la visita.
¿Cuento la conversión?
Separa una recomendación genuina de un autorreferido o de un bot incentivado.
Un vocabulario de cuatro palabras
Cada escenario recibe una de cuatro respuestas, y con ella la base sobre la que se emitió — los ejes decisivos de un vocabulario fijo: bot, riesgo, reputación de fraude, comportamiento, multicuentas, robo de cuenta, red, patrón de afiliado. Siempre sabe qué eje movió el consejo, sin ver nunca nombres de señales, pesos ni umbrales.
Un cálculo, tres canales
El mismo bloque de recomendaciones viaja en el webhook, responde en la Data API y se representa en la ficha del visitante dentro del panel — un solo conjunto de reglas, un solo resultado, ninguna conciliación de su lado. Lea el consejo de su escenario en lugar del global: el global es simplemente el más estricto de los cuatro, un resumen para paneles y no una decisión de pago. La versión de las reglas viaja en la carga útil, de modo que un cambio de reglas es algo que usted nota, no algo que deduce de un consejo que se movió.
"guidance": { "version": 1, "overall": "review", "payment": "review", "registration": "challenge", "login": "allow", "affiliate": "allow", "basis": ["risk", "fraud_reputation"]}Cinco SDK en el frontend, dos canales en el backend
El lado del navegador se publica como cinco SDK: JavaScript puro, React, Vue 3, Angular y Svelte 5. No hay SDK de servidor, y es deliberado: su backend se integra por HTTP plano mediante webhooks firmados y la Data API. Verificar la firma son una docena de líneas contra un vector de referencia que publicamos, y no queda nada extra que ir actualizando en el árbol de dependencias de su servidor.
Preguntas frecuentes
Móntelo en una tarde
Cree un webhook en el panel, apúntelo a su endpoint y pulse Probar. Verifique la firma contra nuestro vector de referencia y lo difícil ya está hecho.