> ## 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 Connection Fingerprint

> Cómo llamar a Connection Fingerprint desde el navegador, verificar la firma en el backend y convertir las señales en decisiones de riesgo.

## El recorrido completo

<Steps>
  <Step title="Solicite el alta de su origen">
    El servicio responde CORS con una lista explícita de orígenes permitidos y `access-control-allow-credentials: true`. Envíe a VU los orígenes exactos —esquema, host y puerto— de cada ambiente antes de empezar.
  </Step>

  <Step title="Llame a la API desde el cliente">
    La huella describe la conexión que hace la llamada. Tiene que salir del dispositivo del usuario.
  </Step>

  <Step title="Envíe la respuesta íntegra a su backend">
    `userData` y `signature`, sin modificar ni reordenar nada.
  </Step>

  <Step title="Verifique la firma y evalúe">
    Recién después de verificar, use las señales en su motor de riesgo.
  </Step>
</Steps>

## Llamar desde el navegador

```js theme={null}
const res = await fetch("https://fingerprint.api.vusecurity.com/", {
  credentials: "include",   // imprescindible: sin esto la cookie fp no viaja
});
const fingerprint = await res.json();

// Enviar TAL CUAL al backend, junto con el contexto de su sesión.
await fetch("/api/riesgo/evaluar", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ sesionId, fingerprint }),
});
```

<Warning>
  **`credentials: "include"` no es opcional.** Sin esa opción la cookie `fp` no se envía ni se guarda, y el servicio emite un identificador nuevo en cada visita. La persistencia —que es la mitad del valor del producto— desaparece en silencio: la respuesta sigue siendo `200` y todos los campos siguen presentes.
</Warning>

<Warning>
  **Nunca llame a esta API desde su servidor en nombre del usuario.** La huella se calcula sobre el handshake TLS de quien llama. Una llamada hecha desde su backend devuelve la huella de su backend: idéntica para todos sus usuarios y, por lo tanto, sin valor alguno.
</Warning>

## Verificar la firma

La respuesta atraviesa el cliente. Sin verificar, cualquiera puede editar `userData` con las herramientas de desarrollo antes de que llegue a su backend.

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

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

El valor es una clave pública RSA de 4096 bits en formato PEM, codificada en base64. Decodifíquela una vez y guárdela en caché; no la pida en cada evaluación.

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

<Warning>
  **Confirme con VU el algoritmo de hash y la canonicalización exacta de `userData`** antes de escribir la verificación. La firma se produce sobre una serialización específica del bloque: si su código vuelve a serializar el objeto con otro formato —otro espaciado, otro orden de claves— la verificación falla aunque los datos sean auténticos. Conserve el cuerpo **crudo** de la respuesta desde el cliente hasta el verificador; no lo pase por `JSON.parse` y `JSON.stringify` en el camino.
</Warning>

<Tip>
  Mientras acuerda ese detalle con VU, no deje la integración abierta: trate la respuesta como no verificada y no permita que por sí sola habilite una operación sensible.
</Tip>

## Usar las señales

Ninguna señal decide sola. El valor está en cruzarlas.

| Observación | Qué sugiere | Con qué cruzarla |
| - | - | - |
| `tlsFingerprintSslGreased` es `"0"` y el `user-agent` dice ser un navegador moderno | Cliente automatizado disfrazado | `headerSignature`, orden de cabeceras |
| `tlsFingerprintHash` conocido, `cookie` y `etag` nuevos | Dispositivo reconocible que perdió el estado | `etagFirstRequest`, historial de la cuenta |
| Mismo `cookie` con `tlsFingerprintHash` distinto | Actualización del navegador… o cookie robada | Ventana temporal, `geoData` |
| `geoData.country` distinto al habitual de la cuenta | Viaje, VPN o toma de cuenta | Velocidad implicada entre eventos, `accuracyRadius` |
| `http2Fingerprint` en `null` desde un navegador moderno | Proxy o cliente intermedio | `headers`, `ip` |

<Warning>
  Un `tlsFingerprintHash` **no es único por dispositivo**: identifica una combinación de cliente, versión y plataforma. Millones de personas con el mismo Chrome en el mismo Windows comparten hash. Sirve para detectar incoherencias y agrupar, jamás para autenticar.
</Warning>

## Persistencia: dos mecanismos, dos vidas

`cookie` y `etag` identifican al mismo visitante por caminos distintos, y esa redundancia es deliberada:

* **`cookie`** vive un año y desaparece cuando el usuario borra sus cookies o abre una ventana privada.
* **`etag`** se apoya en la caché HTTP y suele sobrevivir a ese borrado.
* **`etagFirstRequest`** le dice cuál de los dos casos está viendo: `true` es un `etag` recién emitido, `false` es uno que el cliente devolvió —ya había estado antes—.

Guarde ambos identificadores asociados a la cuenta. Que uno se renueve y el otro persista es, en sí mismo, una señal.

## `/update`

Operación administrativa protegida por la cabecera `X-API-Key`. No interviene en el flujo de integración. Sin una clave válida responde `401`:

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

## Privacidad

<Warning>
  Esta API produce datos personales: dirección IP, ubicación aproximada e identificadores persistentes de dispositivo. En jurisdicciones con GDPR, LGPD o normas equivalentes, su uso requiere base legal, información al titular y un plazo de retención definido. Involucre a su equipo legal antes de salir a producción y guarde solo lo que su motor de riesgo realmente consulta.
</Warning>

## Antes de salir a producción

1. Todos sus orígenes —desarrollo, homologación y producción— están dados de alta en VU.
2. La llamada sale del cliente, nunca de su backend.
3. `credentials: "include"` está presente en cada llamada.
4. El cuerpo crudo de la respuesta llega intacto al verificador.
5. La verificación de firma está implementada y acordada con VU.
6. La clave pública se cachea, con una vía para renovarla.
7. Cada clave de `geoData` se lee como opcional; `city` puede ser `null`.
8. `accuracyRadius` se considera siempre que se usen las coordenadas.
9. Ninguna decisión se apoya en una única señal.
10. Ningún `tlsFingerprintHash` se usa como credencial.
11. Los identificadores tienen un plazo de retención definido y documentado.
12. Existe un camino alternativo para cuando la API no responde: la evaluación de riesgo degrada, no se cae.

<Card title="Volver a la introducción" icon="fingerprint" href="/vucs/connection-fingerprint/introduccion">
  Endpoints, anatomía de la respuesta y significado de cada campo.
</Card>


## Related topics

- [Connection Fingerprint](/vucs/connection-fingerprint/introduccion.md)
- [VU Cloud Services](/vucs/introduccion.md)
- [Documentación técnica de VU](/index.md)
- [Integrar Antispoofing Facial](/vucs/antispoofing-facial/integracion.md)
- [Integrar ID Analysis](/vucs/id-analysis/integracion.md)


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