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

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	Planejado ou habilitado por conta	Entrega push para sistemas internos
WebSocket	Planejado ou habilitado por conta	Streams live e dashboards quase em tempo real

Gere uma chave de API backend

Gere uma chave de API de fingerprint 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 fingerprint 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.

Os registros exportados incluem transaction ID, domínio do cliente, timestamp, referência do cliente e identificador de fingerprint.

Webhooks

A entrega por webhook está planejada ou habilitada para contas selecionadas. Use webhooks quando o seu sistema precisar receber novos datapoints sem consultar a API.

Bons casos de uso para webhooks:

• Enviar eventos de fingerprint para uma fila de fraude
• Enriquecer um SIEM ou pipeline de dados
• Acionar workflows de revisão para sessões suspeitas

Streams WebSocket

A entrega por WebSocket está planejada ou habilitada para contas selecionadas. Use-a quando precisar de um feed live para dashboards, ferramentas de operações ou investigação ativa.