Server API

La Server API permite que su backend lea los datos de identificación que TRACIO ya ha recogido para su workspace: el historial de un visitante, las sesiones individuales y los contadores de velocity de ventana corta.

Complementa a los webhooks en lugar de sustituirlos:

Ambas superficies están disponibles a partir del plan Pro.

URL base

https://api.tracio.ai/v1

Es un host distinto del endpoint del navegador (edge.tracio.ai) y del panel (app.tracio.ai). Los tres están separados: el navegador habla con el edge usando su clave pública, y su backend habla con la Server API usando su clave secreta.

Autenticación

Cada petición lleva su clave secreta como bearer token:

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

La Server API es exclusivamente de servidor a servidor. Las cabeceras CORS deliberadamente no se devuelven, de modo que un navegador no puede llamarla: eso es lo que mantiene su clave secreta fuera del código de cliente. No envíe nunca la clave secreta al navegador.

Cómo obtener una clave secreta

Créela en el panel, en API Keys, eligiendo el tipo secret.

• La clave completa se muestra exactamente una vez, en el momento de crearla. De nuestro lado solo se guarda un hash, así que una clave perdida no se puede recuperar: rótela en su lugar.
• Una clave secreta tiene el aspecto de tracio_sk_ seguido de 43 caracteres, 53 en total. El panel la lista por sus primeros caracteres para que pueda distinguir unas claves de otras.
• Las claves secretas requieren el plan Pro o superior; la clave pública que usa el agente del navegador es un valor aparte, no secreto, de 40 caracteres.

Rotar una clave secreta

La rotación emite una clave nueva y mantiene la antigua en funcionamiento durante 7 días, de modo que pueda desplegarla sin caídas. Despliegue la clave nueva, confirme que el tráfico se ha movido y deje que la antigua expire. Las claves públicas no son rotables: no son secretos y están visibles en el código fuente de sus páginas por diseño.

Endpoints

Toda ruta es un GET. En la Server API no hay operaciones de escritura: lee datos, y su configuración vive en el panel.

Una barra final se acepta y se ignora. Una ruta desconocida o un método equivocado devuelven el mismo sobre de error JSON que todo lo demás, nunca una página HTML o de texto plano.

La ventana temporal

Toda lectura está acotada por una ventana temporal, controlada por dos parámetros de consulta opcionales:

• Una fecha sin hora como to incluye ese día entero.
• Cualquier otra cosa se rechaza con 400 invalid_request y el mensaje time must be YYYY-MM-DD or RFC3339.
• Si no pasa ninguno de los dos, la ventana es todo el periodo de retención de su plan, terminando ahora.
• Una ventana que llegue más atrás de lo que su plan permite se recorta en silencio en vez de rechazarse. La ventana realmente aplicada siempre se informa de vuelta en meta, así que compruebe meta.from y meta.to en lugar de dar por hecho que su petición se respetó al pie de la letra.

Consultar un visitante

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

La respuesta lleva el historial agregado e incrusta la sesión más reciente, así que el caso habitual necesita una petición y no dos:

{
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "firstSeenAt": "2026-05-02T10:11:12Z",
  "lastSeenAt": "2026-07-25T08:00:00Z",
  "visits": 42,
  "incognitoVisits": 3,
  "uniqueIps": 5,
  "uniqueCountries": 2,
  "browsers": ["Chrome"],
  "os": ["macOS"],
  "devices": ["desktop"],
  "risk": {
    "maxRiskScore": 63,
    "avgBotScore": 12.5,
    "botSessions": 7,
    "lastDecision": "real"
  },
  "network": {
    "vpnSeen": false,
    "proxySeen": false,
    "torSeen": false,
    "datacenterSeen": true,
    "lastIsp": "Deutsche Telekom"
  },
  "lastSession": {
    "requestId": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
    "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
    "accountId": "user_8842",
    "timestamp": "2026-07-25T08:00:00Z",
    "tag": "checkout",
    "url": "https://shop.example.com/checkout",
    "ip": "203.0.113.42",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "browser": { "name": "Chrome", "version": "126.0" },
    "os": { "name": "macOS", "version": "14.5" },
    "device": "desktop",
    "geo": {
      "country": "DE",
      "city": "Berlin",
      "timezone": "Europe/Berlin",
      "isp": "Deutsche Telekom"
    },
    "network": {
      "vpn": false,
      "proxy": false,
      "tor": false,
      "datacenter": false,
      "asn": 3320
    },
    "bot": { "result": "human", "score": 4.5, "antidetectScore": 2.1 },
    "identification": {
      "confidence": 0.97,
      "incognito": false,
      "matchType": "exact",
      "matchConfidence": 0.99
    },
    "decision": { "action": "real", "riskScore": 12 }
  },
  "meta": {
    "plan": "business",
    "retentionDays": 90,
    "from": "2026-04-26T00:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

Un visitante sin datos dentro de la ventana de retención devuelve 404 not_found con el mensaje visitor not found in the retention window: eso no es un error de su integración, significa que el visitante es nuevo o que ha quedado fuera por antigüedad.

Campos de veredicto

La sesión lleva dos veredictos y responden a preguntas distintas: si el cliente estaba automatizado y qué concluyó el motor de riesgo en conjunto:

bot.score y decision.riskScore van ambos de 0..100. En Business y superiores, guidance los convierte en recomendaciones por escenario sobre la escala allow → challenge → review → deny; consulte Guidance para saber qué significa cada peldaño.

Listar las sesiones de un visitante

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y/sessions?limit=100&minRiskScore=50"

Las sesiones vuelven de la más reciente a la más antigua:

{
  "items": [
    {
      "requestId": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
      "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
      "timestamp": "2026-07-25T08:00:00Z"
    }
  ],
  "nextCursor": "MTcyMTg5NDQwMDAwMDphYmMxMjM",
  "hasMore": true,
  "meta": {
    "plan": "business",
    "retentionDays": 90,
    "from": "2026-04-26T00:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

Paginación

La paginación se basa en cursores. No hay parámetro page ni offset: devuelva el nextCursor que recibió como cursor y siga mientras hasMore sea true.

async function allSessions(visitorId: string, secretKey: string) {
  const sessions = []
  let cursor: string | undefined

  do {
    const url = new URL(`https://api.tracio.ai/v1/visitors/${visitorId}/sessions`)
    url.searchParams.set("limit", "500")
    if (cursor) url.searchParams.set("cursor", cursor)

    const res = await fetch(url, { headers: { Authorization: `Bearer ${secretKey}` } })
    if (!res.ok) throw new Error(`Server API: ${res.status}`)

    const page = await res.json()
    sessions.push(...page.items)
    cursor = page.nextCursor
  } while (cursor)

  return sessions
}

Trate el cursor como opaco: su contenido es un detalle de implementación y puede cambiar. Un cursor que haya sido editado se rechaza con 400 invalid_request y el mensaje malformed cursor.

Recuperar una sola sesión

La más reciente:

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y/sessions/latest"

Esto devuelve un objeto de sesión a secas: ni un array, ni envuelto en un sobre. Un visitante sin sesiones en la ventana devuelve 404 not_found con no sessions for this visitor in the retention window.

O por requestId, el identificador que también aparece en el payload del webhook:

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/sessions/9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31?visitorId=X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

Aquí visitorId es opcional, pero pasarlo cuando lo conoce hace la búsqueda notablemente más rápida.

Velocity

Velocity responde a «cuánta actividad ha tenido este visitante últimamente»: la forma que tienen el credential stuffing, las pruebas de tarjetas y los registros masivos.

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y/velocity?window=1h"

window acepta 1h, 24h o 7d y por defecto es 24h. Cualquier otro valor se rechaza con 400 invalid_request y window must be one of: 1h, 24h, 7d.

{
  "window": "1h",
  "events": 37,
  "uniqueIps": 9,
  "uniqueCountries": 3,
  "uniqueAccounts": 12,
  "botEvents": 4,
  "meta": {
    "plan": "business",
    "retentionDays": 90,
    "from": "2026-07-25T11:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

uniqueAccounts cuenta los valores linkedId distintos que ha enviado para este dispositivo; consulte Vinculación de cuentas. botEvents es de Business y superiores.

Convenciones de respuesta

Un campo ausente significa «sin datos», nunca cero. Los campos sin valor se omiten por completo en lugar de enviarse como 0, "" o null: un visitante recién llegado no tiene matchConfidence, y una visita limpia no tiene antidetectScore ni suspectScore. La única excepción deliberada es bot.score, que siempre está presente incluso cuando vale cero. Lea los campos de forma defensiva.

El payload depende de su plan. Todo plan con acceso a la API recibe la sesión base: identificadores, timestamp, URL, IP, user agent, navegador, SO, dispositivo, geo, network, bot, identification y decision. Pro añade identification.matchType, identification.matchConfidence y bot.antidetectScore. Business y Enterprise añaden geo.isp, network.asn, decision.suspectScore, identification.driftScore, reasons, behavior, guidance, deviceInfo y los campos a nivel de persona (personId, reputation, linkedAccountsCount, linkedVisitorsCount). Que falte un campo de Business en un plan Pro no es un error.

Los detalles internos a nivel de señal no se devuelven nunca, en ningún plan: los nombres de las señales individuales, sus pesos, los umbrales que hay detrás de un veredicto, los valores en bruto de las señales y el desglose de las puntuaciones se quedan de nuestro lado. Una puntuación que puede someterse a ingeniería inversa hasta sus entradas deja de ser útil como defensa.

Errores

Todo fallo usa un mismo sobre:

{
  "error": {
    "code": "unauthorized",
    "message": "missing Authorization: Bearer <secret key>",
    "requestId": "8f14e45fceea167a5a36dedd"
  }
}

Este requestId no es el identificador de la visita. Dos valores distintos comparten el nombre: dentro de un payload de sesión, requestId es el UUID de la visita, el mismo que entrega el webhook; dentro de un sobre de error es un identificador de traza de 24 caracteres, acuñado para cada llamada HTTP. El identificador de traza vuelve también en la cabecera X-Request-Id en cada respuesta, tenga éxito o no. Inclúyalo cuando contacte con soporte: es como encontramos su llamada exacta.

Las comprobaciones se ejecutan en un orden fijo —clave, luego plan, luego límites—, de modo que una petición con una clave incorrecta siempre informa primero de la clave, nunca de un problema de cuota.

Dos casos de 401 se leen distinto a propósito: missing Authorization: Bearer <secret key> significa que la cabecera nunca llegó, mientras que invalid or revoked API key significa que llegó y no coincidió. El 402 lleva Data API requires the Pro plan or higher.

Límites de tasa y cuotas

Cada respuesta autenticada lleva su situación actual:

• Se permiten ráfagas cortas: el límite por segundo es un token bucket que tolera hasta tres veces la tasa sostenida antes de empezar a rechazar.
• Una petición rechazada por superar la tasa por segundo no consume cuota diaria, así que una ráfaga no puede comerse el presupuesto del día.
• Los límites de la Server API se cuentan aparte del tráfico de identificación. Leer su propio historial nunca gasta las identificaciones que está pagando.

Próximos pasos

• Webhooks — reciba cada identificación en el momento en que ocurre
• Vinculación de cuentas — asocie su propio id de cuenta a un dispositivo
• Detección de bots — cómo se produce el veredicto de bot
• Privacidad y RGPD — gestión de las solicitudes de los interesados