> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vu-one.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrar o Connection Fingerprint

> Como chamar o Connection Fingerprint a partir do navegador, verificar a assinatura no backend e transformar os sinais em decisões de risco.

## O percurso completo

<Steps>
  <Step title="Solicite o cadastro da sua origem">
    O serviço responde CORS com uma lista explícita de origens permitidas e `access-control-allow-credentials: true`. Envie à VU as origens exatas — esquema, host e porta — de cada ambiente antes de começar.
  </Step>

  <Step title="Chame a API a partir do cliente">
    A impressão digital descreve a conexão que faz a chamada. Ela precisa sair do dispositivo do usuário.
  </Step>

  <Step title="Encaminhe a resposta íntegra ao seu backend">
    `userData` e `signature`, sem modificar nem reordenar nada.
  </Step>

  <Step title="Verifique e avalie">
    Só depois de verificar os sinais devem chegar ao seu motor de risco.
  </Step>
</Steps>

## Chamar a partir do navegador

```js theme={null}
const res = await fetch("https://fingerprint.api.vusecurity.com/", {
  credentials: "include",   // indispensável: sem isso o cookie fp não viaja
});
const fingerprint = await res.json();

// Encaminhar EXATAMENTE como veio ao backend, com o contexto da sua sessão.
await fetch("/api/risco/avaliar", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ sessaoId, fingerprint }),
});
```

<Warning>
  **`credentials: "include"` não é opcional.** Sem essa opção o cookie `fp` não é enviado nem armazenado, e o serviço emite um identificador novo a cada visita. A persistência — metade do valor do produto — desaparece em silêncio: a resposta continua sendo `200` e todos os campos continuam presentes.
</Warning>

<Warning>
  **Nunca chame esta API a partir do seu servidor em nome do usuário.** A impressão digital é calculada sobre o handshake TLS de quem chama. Uma chamada feita do seu backend devolve a impressão digital do seu backend: idêntica para todos os seus usuários e, portanto, sem valor algum.
</Warning>

## Verificar a assinatura

A resposta atravessa o cliente. Sem verificação, qualquer pessoa pode editar `userData` nas ferramentas de desenvolvedor antes que ela chegue ao seu backend.

```bash theme={null}
curl -s https://fingerprint.api.vusecurity.com/publicKey
```

```json theme={null}
{ "publicKey": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0K..." }
```

O valor é uma chave pública RSA de 4096 bits em formato PEM, codificada em base64. Decodifique-a uma vez e mantenha em cache; não a busque a cada avaliação.

```js theme={null}
let chave = null;
async function chavePublica() {
  if (chave) return chave;
  const r = await fetch("https://fingerprint.api.vusecurity.com/publicKey");
  const { publicKey } = await r.json();
  chave = Buffer.from(publicKey, "base64").toString("utf8"); // PEM
  return chave;
}
```

<Warning>
  **Confirme com a VU o algoritmo de hash e a canonicalização exata de `userData`** antes de escrever a verificação. A assinatura é produzida sobre uma serialização específica do bloco: se o seu código serializar o objeto novamente em outro formato — outro espaçamento, outra ordem de chaves — a verificação falha mesmo com dados autênticos. Preserve o corpo **bruto** da resposta desde o cliente até o verificador; não o passe por `JSON.parse` e `JSON.stringify` no caminho.
</Warning>

<Tip>
  Enquanto acerta esse detalhe com a VU, não deixe a integração aberta: trate a resposta como não verificada e não permita que ela sozinha autorize uma operação sensível.
</Tip>

## Usar os sinais

Nenhum sinal decide sozinho. O valor está em cruzá-los.

| Observação | O que sugere | Cruze com |
| - | - | - |
| `tlsFingerprintSslGreased` é `"0"` e o `user-agent` diz ser um navegador moderno | Cliente automatizado disfarçado | `headerSignature`, ordem dos cabeçalhos |
| `tlsFingerprintHash` conhecido, `cookie` e `etag` novos | Dispositivo reconhecível que perdeu o estado | `etagFirstRequest`, histórico da conta |
| Mesmo `cookie` com `tlsFingerprintHash` diferente | Atualização do navegador… ou cookie roubado | Janela temporal, `geoData` |
| `geoData.country` diferente do habitual da conta | Viagem, VPN ou tomada de conta | Velocidade implicada entre eventos, `accuracyRadius` |
| `http2Fingerprint` em `null` vindo de um navegador moderno | Proxy ou cliente intermediário | `headers`, `ip` |

<Warning>
  Um `tlsFingerprintHash` **não é único por dispositivo**: identifica uma combinação de cliente, versão e plataforma. Milhões de pessoas com o mesmo Chrome no mesmo Windows compartilham o hash. Serve para detectar incoerências e agrupar, jamais para autenticar.
</Warning>

## Persistência: dois mecanismos, duas vidas

`cookie` e `etag` identificam o mesmo visitante por caminhos distintos, e essa redundância é deliberada:

* **`cookie`** vive um ano e desaparece quando o usuário limpa os cookies ou abre uma janela anônima.
* **`etag`** se apoia no cache HTTP e costuma sobreviver a essa limpeza.
* **`etagFirstRequest`** diz qual dos dois casos você está vendo: `true` é um `etag` recém-emitido, `false` é um que o cliente devolveu — já esteve aqui antes.

Guarde os dois identificadores associados à conta. Um renovar enquanto o outro persiste é, por si só, um sinal.

## `/update`

Operação administrativa protegida pelo cabeçalho `X-API-Key`. Não participa do fluxo de integração. Sem uma chave válida responde `401`:

```json theme={null}
{ "detail": "Invalid API Key" }
```

## Privacidade

<Warning>
  Esta API produz dados pessoais: endereço IP, localização aproximada e identificadores persistentes de dispositivo. Sob a LGPD, o GDPR ou normas equivalentes, seu uso exige base legal, informação ao titular e um prazo de retenção definido. Envolva o seu time jurídico antes de ir para produção e guarde apenas o que o seu motor de risco realmente consulta.
</Warning>

## Antes de ir para produção

1. Todas as suas origens — desenvolvimento, homologação e produção — estão cadastradas na VU.
2. A chamada sai do cliente, nunca do seu backend.
3. `credentials: "include"` está presente em cada chamada.
4. O corpo bruto da resposta chega intacto ao verificador.
5. A verificação de assinatura está implementada e combinada com a VU.
6. A chave pública fica em cache, com um caminho para renová-la.
7. Cada chave de `geoData` é lida como opcional; `city` pode ser `null`.
8. `accuracyRadius` é considerado sempre que as coordenadas forem usadas.
9. Nenhuma decisão se apoia em um único sinal.
10. Nenhum `tlsFingerprintHash` é usado como credencial.
11. Os identificadores têm um prazo de retenção definido e documentado.
12. Existe um caminho alternativo para quando a API não responde: a avaliação de risco degrada, não cai.

<Card title="Voltar à introdução" icon="fingerprint" href="/pt/vucs/connection-fingerprint/introducao">
  Endpoints, anatomia da resposta e significado de cada campo.
</Card>


## Related topics

- [Connection Fingerprint](/pt/vucs/connection-fingerprint/introducao.md)
- [VU Cloud Services](/pt/vucs/introducao.md)
- [Documentação técnica da VU](/pt/index.md)
- [Integrar o Antispoofing Facial](/pt/vucs/antispoofing-facial/integracao.md)
- [Changelog da Identity Link API](/pt/identity-link/changelog.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.