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

# Connection Fingerprint

> API de impressão digital de conexão da VU: identifica um dispositivo pela assinatura TLS, pelos cabeçalhos e pela origem geográfica, sem JavaScript de rastreamento.

O **Connection Fingerprint** identifica um dispositivo por *como* ele se conecta, não pelo que ele diz ser. Em uma única chamada devolve a assinatura TLS do cliente, a assinatura dos seus cabeçalhos HTTP, a origem geográfica aproximada e um identificador persistente — tudo derivado do próprio handshake da conexão.

Serve para reconhecer um dispositivo que retorna, detectar automação se passando por navegador e somar sinais a um motor de risco. Não exige SDK, não executa código no cliente e não depende das APIs de navegador que os modos de privacidade bloqueiam.

<Note>
  Os sinais desta API são **insumo para decidir**, não um veredito. Diferentemente do [Antispoofing Facial](/pt/vucs/antispoofing-facial/introducao), aqui não há um campo que diga «suspeito»: você combina esses sinais com a sua própria lógica de risco.
</Note>

## Como funciona

```mermaid theme={null}
sequenceDiagram
    participant N as Navegador ou cliente
    participant F as Connection Fingerprint
    participant B as Seu backend
    N->>F: GET / (com o cookie fp, se já existir)
    F-->>N: { userData, signature } + Set-Cookie fp
    N->>B: Encaminha a resposta completa
    B->>B: Verifica a assinatura e avalia o risco
```

O cliente chama o serviço diretamente: a impressão digital é derivada **daquela** conexão TLS, então uma chamada feita a partir do seu servidor descreveria o seu servidor, não o usuário. A resposta segue depois para o seu backend, onde é verificada e usada.

## Endpoints

URL base: `https://fingerprint.api.vusecurity.com`

| Método | Caminho | Autenticação | Para que serve |
| - | - | - | - |
| `GET` | `/` | Nenhuma | Obter a impressão digital da conexão atual. |
| `GET` | `/version` | Nenhuma | Versão do serviço. |
| `GET` | `/publicKey` | Nenhuma | Chave pública RSA para verificar `signature`. |
| `GET` | `/update` | `X-API-Key` | Operação administrativa da VU. Não faz parte do fluxo de integração. |

<Note>
  `/`, `/version` e `/publicKey` são públicos por design: o navegador do usuário final precisa poder chamá-los sem credenciais. O que protege a integração não é uma api-key, e sim a verificação da assinatura no seu backend.
</Note>

## Primeira chamada

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

```json theme={null}
{
  "userData": {
    "timeStampUtc": "2026-08-22T13:19:24.013555",
    "http2Fingerprint": null,
    "http2FingerprintHash": null,
    "tlsFingerprint": "771,4866-4865-49196-49195-49200-49199-...",
    "tlsFingerprintHash": "2800f914a7a4ba98aa9df62d316a460c",
    "tlsFingerprintSslGreased": "0",
    "headers": {
      "x-forwarded-for": "203.0.113.42",
      "host": "fingerprint.api.vusecurity.com",
      "user-agent": "Mozilla/5.0 ...",
      "accept": "*/*"
    },
    "headerSignature": "dd847632ef6fa4c27394ea149c58f34a",
    "etag": "UNTLLK5S-21550",
    "etagFirstRequest": true,
    "geoData": {
      "accuracyRadius": 10,
      "latitude": -36.0,
      "longitude": -59.9964,
      "country": "Argentina",
      "countryIso": "AR",
      "city": null,
      "subdivisions": "Buenos Aires",
      "subdivisionsIso": "B"
    },
    "ip": "203.0.113.42",
    "cookie": "8L3KA06LD6I9N4PUUOV5SQ74Y6H78Q7Z"
  },
  "signature": "Fdnb/bD3UGWmkcUByAmWahDXLADJJa0qCFubqr0ESnTW..."
}
```

## Anatomia da resposta

### Identidade da conexão

| Campo | O que é |
| - | - |
| `tlsFingerprint` | A impressão digital JA3 completa do cliente: versão, cifras, extensões e curvas oferecidas no handshake TLS, nessa ordem. |
| `tlsFingerprintHash` | Hash MD5 do valor acima. É o valor prático para comparar e agrupar. |
| `tlsFingerprintSslGreased` | `"1"` se o cliente usou valores GREASE (RFC 8701). Navegadores modernos usam; muitas bibliotecas HTTP não. |
| `http2Fingerprint` / `http2FingerprintHash` | Impressão digital da camada HTTP/2. `null` quando a conexão não chegou por HTTP/2. |
| `headers` | Os cabeçalhos que o cliente enviou, exatamente como chegaram. |
| `headerSignature` | Hash do conjunto de cabeçalhos: sua ordem e presença são tão características quanto o conteúdo. |

<Tip>
  O sinal mais útil não é um campo isolado, e sim a **coerência entre eles**. Um `user-agent` que diz ser Chrome ao lado de um `tlsFingerprintHash` que não corresponde a nenhum Chrome conhecido, ou com `tlsFingerprintSslGreased` em `"0"`, descreve um cliente que afirma ser algo que não é.
</Tip>

### Persistência

| Campo | O que é |
| - | - |
| `cookie` | Identificador persistente. O serviço o emite em um cookie `fp` com um ano de validade, `HttpOnly`, `Secure` e `SameSite=None`. |
| `etag` | Identificador baseado no mecanismo de cache HTTP. Sobrevive à limpeza de cookies em vários navegadores. |
| `etagFirstRequest` | `true` quando o `etag` foi emitido nesta chamada; `false` quando o cliente o devolveu, ou seja, já esteve aqui antes. |

### Origem

| Campo | O que é |
| - | - |
| `ip` | Endereço de origem observado. |
| `geoData.accuracyRadius` | Raio de precisão em quilômetros. **Leia-o sempre junto com as coordenadas.** |
| `geoData.latitude` / `longitude` | Centro da área estimada, não a posição do dispositivo. |
| `geoData.country` / `countryIso` | País e seu código ISO 3166-1 alfa-2. |
| `geoData.subdivisions` / `subdivisionsIso` | Divisão administrativa e seu código. |
| `geoData.city` | Cidade. **Frequentemente `null`.** |

<Warning>
  A geolocalização por IP é aproximada e vários de seus campos podem chegar como `null`. Trate cada chave de `geoData` como opcional e nunca a use como única prova de localização: uma VPN, uma rede corporativa ou um CGNAT deslocam o resultado em centenas de quilômetros sem que nada na resposta indique isso.
</Warning>

### Integridade

`signature` é uma assinatura RSA de 4096 bits produzida com a chave privada da VU sobre o bloco `userData`. Existe porque a resposta passa pelo cliente antes de chegar ao seu backend — e o cliente é exatamente a parte em que não convém confiar.

<Card title="Integração" icon="code" href="/pt/vucs/connection-fingerprint/integracao">
  Como chamá-la a partir do navegador, o que fazer com a resposta e como usar os sinais.
</Card>


## Related topics

- [Integrar o Connection Fingerprint](/pt/vucs/connection-fingerprint/integracao.md)
- [VU Cloud Services](/pt/vucs/introducao.md)
- [Documentação técnica da VU](/pt/index.md)
- [Changelog da Identity Link API](/pt/identity-link/changelog.md)
- [Ler Resultados KYC de Verificações de Identidade](/pt/identity-link/kyc.md)


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