Recuperar datapoints

O navegador não precisa saber o que sendClientTelemetry(externalIds?) envia internamente. Chame a função, leia o token de sessão retornado e deixe que o seu backend troque esse token de sessão com https://api.cside.com/token/v2/verify para recuperar datapoints de fingerprint, bot, navegador, dispositivo, IP e ambiente.

Fluxo de ponta a ponta

1. O navegador chama sendClientTelemetry(externalIds?).
2. sendClientTelemetry envia telemetria para o CLIENT_URL configurado, normalmente /client.
3. /client retorna JSON no formato { "token": "..." }, em que token é o token de sessão de fingerprint.
4. O seu backend envia esse token de sessão para https://api.cside.com/token/v2/verify com uma chave de API de Device Intelligence do servidor.

Uso de sendClientTelemetry

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

if (result.errors) {
  console.error(result.errors);
  throw new Error("A solicitação de telemetria falhou.");
}

const { token: sessionToken } = result;

if (!sessionToken) {
  throw new Error("Nenhum token de sessão de fingerprint foi retornado.");
}

Depois de extrair sessionToken, envie-o ao seu backend. O seu backend faz a troca do token com o cside.

Você também pode chamar sendClientTelemetry() sem argumentos. Use externalIds apenas quando quiser anexar os seus próprios identificadores, como accountId, orderId ou email, ao fingerprint.

O exemplo acima usa o sendClientTelemetry que o client.js expõe em window. Se você instalou o pacote NPM, pegue a mesma função a partir de initDeviceIntelligence e ganhe tipos com ela:

import { initDeviceIntelligence } from "@cside.dev/device-intelligence";

const { sendClientTelemetry } = await initDeviceIntelligence({
  teamID: "[your-team-id]",
});

Tudo abaixo vale nos dois casos. A função, os argumentos e o token de sessão devolvido são os mesmos.

Detecção de fraude com os últimos quatro dígitos do cartão

Um caso de uso comum de fraude no checkout é detectar um fingerprint de dispositivo que tenta pagar com muitos cartões diferentes. Você pode anexar os últimos quatro dígitos do cartão de pagamento como outro identificador externo e depois revisar a atividade de fingerprint resultante a partir do seu backend.

const result = await sendClientTelemetry({
  accountId: "1234567890",
  orderId: "order-456",
  cardLast4: "4242",
});

Envie apenas os últimos quatro dígitos. Não envie o número completo do cartão, CVC, data de validade nem outros dados brutos de cartão de pagamento por meio de externalIds.

Opções de recuperação

Método	Status	Melhor para
API	Disponível	Decisões no tempo da requisição e enriquecimento no backend
Exportação S3	Disponível quando ativada	Análise batch, data warehouse e revisão offline
Webhook	Não disponível	Entrega push para sistemas internos
WebSocket	Não disponível	Streams live e dashboards quase em tempo real

Gere uma chave de API backend

Gere uma chave de API de Device Intelligence no dashboard do cside antes de chamar o endpoint autenticado. A chave começa com cside_tgatv1_, é exibida apenas uma vez e deve ser armazenada no gerenciador de segredos do seu backend.

A chave de API é uma credencial de backend associada ao time. Não a envie ao navegador, não a exponha em bundles frontend nem a escreva em HTML a partir de um Worker.

Recuperação por API com o token de sessão

O token de sessão não contém o payload fingerprint completo. Use-o como token de lookup a partir do seu backend com o endpoint autenticado do cside.

Use /token/v2/verify quando precisar do payload JSON completo em uma integração 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"'"}'

O endpoint retorna 202 Accepted com { "status": "pending" } enquanto a avaliação ainda está em processamento. Ele retorna 200 OK com o payload concluído quando o enriquecimento termina.

Exemplo de request no 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 || "A busca de fingerprint falhou.");
}

A resposta concluída inclui status, created_at, updated_at e os campos de enriquecimento disponíveis, como vpn_evaluation, fingerprint, geo_data, ip_enrichment, bot, network_client_metrics e fingerprint_enrichment.

Recupere avaliações anteriores do mesmo dispositivo

Use /token/v2/device/entries quando precisar de avaliações concluídas associadas ao mesmo ID de dispositivo do token de sessão. Isso é útil para pontuação de risco de conta, filas de revisão de fraude, investigação de abuso e para vincular uma nova sessão à atividade recente do mesmo fingerprint de navegador.

O endpoint usa a mesma chave de API de Device Intelligence somente para backend que /token/v2/verify. Ele retorna resultados do mais recente para o mais antigo e oferece paginação com limit e 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 da requisição

Campo	Tipo	Obrigatório	Descrição
token	string	Sim	Token de sessão retornado por sendClientTelemetry.
limit	number	Não	Número máximo de entradas a retornar. O padrão é 500 e o limite máximo é 500.
offset	number	Não	Número de entradas a pular a partir do resultado mais recente. O padrão é 0. Use o next_offset da resposta anterior para solicitar a próxima página.

Body da resposta

A resposta contém o device_id resolvido, um array entries e metadados de paginação. Cada entrada usa o mesmo formato 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	Descrição
device_id	string	ID de dispositivo resolvido a partir do token de sessão.
entries	array	Avaliações concluídas para esse ID de dispositivo, ordenadas da mais recente para a mais antiga.
limit	number	Tamanho efetivo da página depois da limitação aplicada pelo servidor.
offset	number	Offset usado para esta resposta.
next_offset	number | null	Offset a enviar na próxima requisição. null significa que não há mais entradas.
has_more	boolean	true quando outra página está disponível.

Exemplo de backend

Use next_offset da resposta em vez de calcular offsets manualmente. Pare quando has_more for 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 || "A busca de entradas do dispositivo falhou.");
    }

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

  return entries;
}

Se precisar apenas da primeira página, omita limit e offset. A API retorna até 500 avaliações concluídas por padrão.

Endpoints públicos de token

/token/v1/client e /token/v1/clientId continuam disponíveis para integrações que precisam especificamente do fluxo público não autenticado.

Use /token/v1/client quando precisar do payload JSON público sem autenticação por chave de 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 quando precisar apenas do fingerprint ID estável.

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

Para /token/v1/*, envie o token de sessão bruto no corpo da request e não o envolva em JSON. O endpoint clientId retorna texto simples. Se não existir fingerprint ID para o token de sessão, ele retorna 404.

Exportação S3

O cside pode exportar registros de fingerprint para S3 quando a exportação fingerprint S3 estiver configurada para um domínio. Use isso para workflows batch em que você não precisa de uma decisão no tempo da requisição.

Cada registro exportado é a avaliação completa, não um resumo: os campos de identidade, o fingerprint completo do dispositivo e os sinais de rede, IP, geo, VPN, bot, de regras e comportamentais que o cside calculou para aquela visita. Veja o guia da exportação S3 para os passos de configuração e a estrutura completa do registro.

Webhooks e streams WebSocket

Nenhum dos dois está disponível. O S3 é o único destino de exportação para dados de Device Intelligence, e não existe chave por conta que habilite entrega por webhook ou WebSocket.

Se você precisar dos dados fora de uma janela batch, chame a API no tempo da requisição.