Recuperar datapoints

El navegador no necesita saber qué envía internamente sendClientTelemetry(externalIds?). Llame a la función, lea el token de sesión devuelto y deje que su backend intercambie ese token de sesión con https://api.cside.com/token/v2/verify para recuperar datapoints de fingerprint, bot, navegador, dispositivo, IP y entorno.

Flujo de extremo a extremo

1. El navegador llama a sendClientTelemetry(externalIds?).
2. sendClientTelemetry envía telemetría a https://edge.csidefd.com/client. Permita ese host en el connect-src de su CSP.
3. /client devuelve JSON con la forma { "token": "..." }, donde token es el token de sesión de fingerprint.
4. Su backend envía ese token de sesión a https://api.cside.com/token/v2/verify con una clave API de Device Intelligence del servidor.

Uso de sendClientTelemetry

const result = await sendClientTelemetry({
  email: "user@example.com",
  userId: "1234567890",
});

if (result.errors) {
  console.error(result.errors);
  throw new Error("La solicitud de telemetría falló.");
}

const { token: sessionToken } = result;

if (!sessionToken) {
  throw new Error("No se devolvió ningún token de sesión de fingerprint.");
}

Después de extraer sessionToken, envíelo a su backend. Su backend realiza el intercambio del token con cside.

También puede llamar a sendClientTelemetry() sin argumentos. Use externalIds solo cuando quiera adjuntar sus propios identificadores, como userId, orderId o email, al fingerprint.

El ejemplo anterior usa el sendClientTelemetry que client.js expone en window. Si instaló el paquete NPM, tome la misma función desde initDeviceIntelligence y obtenga tipos con ella:

let token = null;

try {
  const { initDeviceIntelligence } = await import("@cside.dev/device-intelligence");
  const { sendClientTelemetry } = await initDeviceIntelligence({
    teamID: "[your-team-id]",
  });
  const result = await sendClientTelemetry({ userId: "1234567890" });
  token = result.token;
  if (result.errors) console.warn(result.errors);
} catch (error) {
  console.warn("Device Intelligence unavailable", error);
}

La importación dinámica permite al empaquetador separar el código de recopilación en otro fragmento. Inicia la importación y la inicialización lo antes posible: esperar hasta el pago o el inicio de sesión retrasa la recopilación y puede perder señales anteriores. Captura los fallos de importación y de inicialización, y mantén la página operativa sin token.

Todo lo que sigue aplica en ambos casos. La función, sus argumentos y el token de sesión que devuelve son los mismos.

Elija sus identificadores externos

externalIds acepta cualquier clave de tipo string, pero dos de ellas alimentan detecciones integradas:

El Identity graph vincula un dispositivo con una cuenta mediante userId, teamId o customerId; sin una de esas claves, la sesión no tiene ninguna cuenta con la que vincularse.

Un caso de uso común de fraude en checkout es detectar un dispositivo que intenta pagar con muchas tarjetas distintas. Adjunte paymentCardId en el momento del pago:

const result = await sendClientTelemetry({
  userId: "1234567890",
  orderId: "order-456",
  // Nunca el número de la tarjeta: un hash unidireccional de él, más los últimos 4 dígitos como máximo.
  paymentCardId: "a3f5c8d19b02e74f_4242",
});

La misma tarjeta debe producir siempre el mismo paymentCardId, así que use un hash determinista o el token de tarjeta de su procesador, nunca un ID por intento. No envíe el número completo de la tarjeta, el CVC, la fecha de vencimiento ni otros datos sin procesar de la tarjeta de pago mediante externalIds.

Opciones de recuperación

Genere una clave API backend

Genere una clave API de Device Intelligence en Team Settings > Device Intelligence del dashboard de cside antes de llamar al endpoint autenticado. La clave empieza con cside_tgatv1_, se muestra solo una vez y debe guardarse en el gestor de secretos de su backend.

La clave API es una credencial backend asociada al equipo. No la envíe al navegador, no la exponga en bundles frontend ni la escriba en HTML desde un Worker.

Recuperación por API con el token de sesión

El token de sesión no contiene el payload fingerprint completo. Úselo como token de lookup desde su backend con el endpoint autenticado de cside.

Use /token/v2/verify cuando necesite el payload JSON completo desde una integración server-to-server.

curl https://api.cside.com/token/v2/verify \
  --request POST \
  --header "Authorization: Bearer $CSIDE_FINGERPRINT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"token":"'"$CSIDE_FINGERPRINT_SESSION_TOKEN"'"}'

El endpoint devuelve 202 Accepted con { "status": "pending" } mientras la evaluación sigue en proceso. Devuelve 200 OK cuando la evaluación termina, con "status": "completed" y el payload, o con "status": "failed" y un error_message.

Ejemplo de request backend:

const csideResponse = await fetch("https://api.cside.com/token/v2/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CSIDE_FINGERPRINT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ token: sessionToken }),
});

const datapoints = await csideResponse.json();

if (!csideResponse.ok) {
  throw new Error(datapoints.error || "La búsqueda de fingerprint falló.");
}

if (datapoints.status === "failed") {
  throw new Error(datapoints.error_message || "La evaluación de fingerprint falló.");
}

La respuesta completada incluye status, created_at, updated_at y los campos de enriquecimiento disponibles: fingerprint, network_client_metrics, geo_data, ip_enrichment, vpn_evaluation, bot, fingerprint_enrichment, rule_evaluations_v2 y el legado rule_evaluations. Consulte la referencia de la respuesta de /token/v2/verify para ver cada campo.

Errores y límites de solicitudes

Las respuestas de error llevan un body JSON { "error": "<message>", "code": <HTTP status> }, no error_message:

El límite de solicitudes predeterminado es de 1.000 solicitudes por minuto por equipo, con ráfagas cortas permitidas. Espere el periodo indicado en retry-after antes de reintentar.

Explicaciones de reglas

Las reglas publicadas que se evalúan como verdaderas pueden incluir rule_evaluations_v2.values[].evaluation.explanation.nodes. Cada nodo visitado puede describir su node_id, outcome, valor tipado observed, subject y compared_to. Las explicaciones son opcionales; los resultados falsos, pendientes o sin datos no las incluyen. La ausencia de explicación no cambia el resultado registrado.

Trata subject y compared_to como texto para mostrar, no como un formato que analizar. Usa node_id, los valores tipados de observed y outcome en tu código. Lee estos campos de rule_evaluations_v2, no del objeto heredado rule_evaluations. Consulta la API de eventos para ver los valores y la diferencia con los resultados heredados.

Recupere evaluaciones anteriores del mismo dispositivo

Use /token/v2/device/entries cuando necesite evaluaciones completadas asociadas al mismo ID de dispositivo que el token de sesión. Es útil para scoring de riesgo de cuenta, colas de revisión de fraude, investigación de abuso y para vincular una nueva sesión con actividad reciente del mismo fingerprint de navegador.

El endpoint usa la misma clave API de Device Intelligence solo para backend que /token/v2/verify. Devuelve resultados del más reciente al más antiguo y admite paginación con limit y offset.

curl https://api.cside.com/token/v2/device/entries \
  --request POST \
  --header "Authorization: Bearer $CSIDE_FINGERPRINT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "token": "'"$CSIDE_FINGERPRINT_SESSION_TOKEN"'",
    "limit": 100,
    "offset": 0
  }'

Body de la solicitud

Body de la respuesta

La respuesta contiene el device_id resuelto, un array entries y metadatos de paginación. Cada entrada usa la misma forma de payload plano que /token/v2/verify.

{
  "device_id": "a1b2c3d4e5f6...",
  "entries": [
    {
      "status": "completed",
      "created_at": 1779441600000,
      "updated_at": 1779441600000,
      "fingerprint": {},
      "network_client_metrics": {}
    }
  ],
  "limit": 100,
  "offset": 0,
  "next_offset": 100,
  "has_more": true
}

Ejemplo backend

Use next_offset desde la respuesta en lugar de calcular offsets manualmente. Deténgase cuando has_more sea false.

async function fetchDeviceEntries(sessionToken) {
  const entries = [];
  let offset = 0;
  const limit = 100;

  while (offset !== null) {
    const response = await fetch("https://api.cside.com/token/v2/device/entries", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.CSIDE_FINGERPRINT_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        token: sessionToken,
        limit,
        offset,
      }),
    });

    const page = await response.json();

    if (!response.ok) {
      throw new Error(page.error || "La búsqueda de entradas del dispositivo falló.");
    }

    entries.push(...page.entries);
    offset = page.has_more ? page.next_offset : null;
  }

  return entries;
}

Si solo necesita la primera página, omita limit y offset. La API devuelve hasta 500 evaluaciones completadas de forma predeterminada.

Endpoints públicos de token

/token/v1/client y /token/v1/clientId siguen disponibles para integraciones que necesitan específicamente el flujo público no autenticado.

Use /token/v1/client cuando necesite el payload JSON público sin autenticación por clave API.

curl https://api.cside.com/token/v1/client \
  --request POST \
  --header "Content-Type: text/plain" \
  --data "$CSIDE_FINGERPRINT_SESSION_TOKEN"

Use /token/v1/clientId cuando solo necesite el fingerprint ID estable.

curl https://api.cside.com/token/v1/clientId \
  --request POST \
  --header "Content-Type: text/plain" \
  --data "$CSIDE_FINGERPRINT_SESSION_TOKEN"

Para /token/v1/*, envíe el token de sesión sin procesar como body text/plain y no lo envuelva en JSON. Solo los endpoints /token/v2/* aceptan { "token": "..." }. Ambos endpoints v1 devuelven 202 Accepted con { "status": "pending" } mientras la evaluación está en proceso. /token/v1/clientId devuelve después JSON:

{ "status": "completed", "device_id": "a1b2c3d4e5f6..." }

Si no existe un fingerprint ID para el token de sesión, devuelve 404 con { "error": "fingerprint id not found", "code": 404 }. Los endpoints v1 comparten la misma forma de error y el mismo límite de solicitudes que /token/v2/verify, aplicado según el equipo del token.

Exportación S3

cside puede exportar registros de fingerprint a S3 cuando la exportación fingerprint S3 está configurada para un dominio. Use esto para workflows batch donde no necesite una decisión en tiempo de solicitud.

Cada registro exportado es la evaluación completa, no un resumen: los campos de identidad, el fingerprint completo del dispositivo y las señales de red, IP, geolocalización, VPN, bots, comportamiento y reglas que cside calculó para esa visita. Consulte la guía de exportación S3 para ver los pasos de configuración y la estructura completa del registro.

Webhooks y streams WebSocket

Ninguno de los dos está disponible. S3 es el único destino de exportación para los datos de Device Intelligence, y no existe ningún ajuste a nivel de cuenta que habilite la entrega por webhook o por WebSocket.

Si necesita datos fuera de una ventana batch, llame a la API en tiempo de solicitud.