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 al CLIENT_URL configurado, normalmente /client.
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 fingerprint del servidor.

Uso de sendClientTelemetry

const result = await sendClientTelemetry({
  email: "user@example.com",
  accountId: "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 accountId, orderId o email, al fingerprint.

Opciones de recuperación

Método	Estado	Mejor para
API	Disponible	Decisiones en tiempo de solicitud y enriquecimiento backend
Exportación S3	Disponible cuando está habilitada	Análisis batch, data warehouse y revisión offline
Webhook	Planificado o habilitado por cuenta	Entrega push hacia sistemas internos
WebSocket	Planificado o habilitado por cuenta	Streams live y dashboards casi en tiempo real

Genere una clave API backend

Genere una clave API de fingerprint en el 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 con el payload completado cuando termina el enriquecimiento.

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_message || "La búsqueda de fingerprint falló.");
}

La respuesta completada incluye status, created_at, updated_at y los campos de enriquecimiento disponibles, como vpn_evaluation, fingerprint, geo_data, ip_enrichment, bot, network_client_metrics y fingerprint_enrichment.

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

Campo	Tipo	Obligatorio	Descripción
token	string	Sí	Token de sesión devuelto por sendClientTelemetry.
limit	number	No	Número máximo de entradas que se devolverán. El valor predeterminado es 500 y el máximo permitido es 500.
offset	number	No	Número de entradas que se omiten desde el resultado más reciente. El valor predeterminado es 0. Use el next_offset de la respuesta anterior para solicitar la página siguiente.

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
}

Campo	Tipo	Descripción
device_id	string	ID de dispositivo resuelto desde el token de sesión.
entries	array	Evaluaciones completadas para ese ID de dispositivo, ordenadas de la más reciente a la más antigua.
limit	number	Tamaño efectivo de página después del límite aplicado por el servidor.
offset	number	Offset usado para esta respuesta.
next_offset	number | null	Offset que se debe enviar en la siguiente solicitud. null significa que no hay más entradas.
has_more	boolean	true cuando hay otra página disponible.

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 en el body de la request y no lo envuelva en JSON. El endpoint clientId devuelve texto plano. Si no existe un fingerprint ID para el token de sesión, devuelve 404.

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.

Los registros exportados incluyen transaction ID, dominio del cliente, timestamp, referencia del cliente e identificador de fingerprint.

Webhooks

La entrega por webhook está planificada o habilitada para cuentas seleccionadas. Use webhooks cuando su sistema deba recibir nuevos datapoints sin consultar la API.

Buenos casos de uso para webhooks:

• Enviar eventos de fingerprint a una cola de fraude
• Enriquecer un SIEM o pipeline de datos
• Activar workflows de revisión para sesiones sospechosas

Streams WebSocket

La entrega por WebSocket está planificada o habilitada para cuentas seleccionadas. Úsela cuando necesite un feed live para dashboards, herramientas de operaciones o investigación activa.