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

# Guía de integración

> Cómo integrar Face Analysis: preparar las imágenes, alinear operations con images, armar la llamada y validar la integración antes de producción.

## El flujo en cuatro pasos

<Steps>
  <Step title="Verifique la conectividad">
    `GET /version` con su `Api-Key` (no la exige, pero así prueba la cabecera completa). Debe responder `200`. Evalúe el código de estado, no el cuerpo: su formato no forma parte del contrato. Si falla, el problema es de URL, red o proxy — todavía no hay nada que depurar del lado de la API.
  </Step>

  <Step title="Prepare las imágenes">
    JPEG o PNG, en base64 **sin** el prefijo `data:` y sin saltos de línea. Un rostro por imagen, de frente, bien iluminado.
  </Step>

  <Step title="Declare las operaciones">
    `operations` es una **lista de listas alineada con `images`**: `operations[i]` aplica a `images[i]`. Si la omite, cada imagen corre `biometric` por defecto.
  </Step>

  <Step title="Decida con la regla en positivo">
    `status === 200 && biometric["0"]["1"] >= 70` confirma; cualquier otra cosa no confirma. Los detalles del umbral están en la [introducción](/vucs/face-analysis/introduccion).
  </Step>
</Steps>

## Requisitos de imagen

| Aspecto | Requisito |
| - | - |
| Resolución mínima dura | **160 × 160 px** — por debajo, el servicio devuelve `400`. |
| Resolución recomendada | **≥ 360 × 360 px** — por debajo de 360, el veredicto de calidad se degrada automáticamente a `low`, aunque el HTTP siga en `200`. |
| Rostro | Uno solo por imagen, de frente, ojos visibles. |
| Compresión | JPEG calidad **≥ 90**. La compresión agresiva degrada los atributos y el puntaje biométrico. |
| Codificación | Base64 estándar, sin prefijo `data:`, sin saltos de línea. |

Para convertir una imagen a base64:

<CodeGroup>
  ```powershell Windows (PowerShell) theme={null}
  [Convert]::ToBase64String([IO.File]::ReadAllBytes('C:\ruta\selfie.jpg')) | Set-Clipboard
  ```

  ```bash Linux theme={null}
  base64 -w0 selfie.jpg
  ```

  ```bash macOS theme={null}
  base64 -i selfie.jpg | pbcopy
  ```
</CodeGroup>

## El cuerpo de la solicitud

| Campo | Tipo | Qué hace |
| - | - | - |
| `info` | string, **obligatorio** | Su referencia de la operación, de 2 a 256 caracteres. Vuelve tal cual en la respuesta. |
| `images` | string\[], **obligatorio** | Las imágenes en base64. |
| `operations` | string\[]\[] | Las operaciones por imagen, alineadas con `images`. Omitida ⇒ `biometric` para todas. |
| `faceVectors` | number\[]\[] | Vectores biométricos guardados (512 valores) para comparar contra las imágenes. Continúan la numeración después de las imágenes. |
| `distanceMethodology` | string | `vu_v4` (por defecto), `cosine` o `euclidean_l2`. Cambia la **escala** del puntaje. |
| `returnFaceVector` | boolean | Devuelve el vector de 512 valores de cada rostro, para guardarlo y comparar después sin la foto. |
| `returnFaceImage` | boolean | Devuelve el recorte alineado del rostro en base64. |
| `events` | boolean | Agrega la traza interna de ejecución. Solo para diagnóstico. |

<Warning>
  **`operations` desalineado no es un `400` prolijo.** Una lista `operations` más corta que `images` produce un `500` con cuerpo en **texto plano** (`Internal Server Error`), y omitir `images` también. Valide la alineación antes de llamar; esos errores son de su solicitud y reintentarlos devuelve exactamente lo mismo.
</Warning>

## Los tres modos de comparar

```json theme={null}
// 1. Selfie vs foto del documento: dos imágenes
{ "info": "op-1", "images": ["<selfie>", "<docFace>"], "operations": [["biometric"], ["biometric"]] }

// 2. Selfie vs vector guardado: una imagen + un faceVector
//    El vector continúa la numeración: la selfie es "0", el vector es "1".
{ "info": "op-2", "images": ["<selfie>"], "faceVectors": [[0.031, -0.114, "...512 valores"]] }

// 3. Enrolar: pedir el vector para guardarlo
{ "info": "op-3", "images": ["<selfie>"], "returnFaceVector": true }
```

<Note>
  Si guarda vectores para comparar después, guarde también **con qué metodología** se generaron y compare siempre con la misma. Un vector `vu_v4` comparado con `euclidean_l2` da puntajes de otra escala y su umbral deja de valer.
</Note>

## Un lote no tolera fallas parciales

Si envía 4 imágenes y la tercera no tiene rostro, no recibe 3 resultados y un error: recibe **un solo `400`** con `imageNumber: 2` (base 0) y ningún resultado. No hay resultados parciales. Si su flujo tolera fallas por imagen, envíe una solicitud por imagen.

## Timeouts y reintentos

| Situación | Política |
| - | - |
| Timeout de lectura | **30 s** — cada imagen del lote suma tiempo de proceso. |
| `500` esporádico | Reintentar con backoff, máximo 2 veces. |
| `500` que vuelve idéntico | Es su solicitud (`images` ausente u `operations` desalineado). No reintentar: corregir. |
| No-match o `spoofing: true` | **Nunca** reintentar con la misma imagen: el resultado es determinístico. |
| `400` / `401` / `422` | No reintentar: corregir la solicitud o la credencial. |

## Antes de salir a producción

1. `GET /version` responde `200` en el ambiente de producción con su conectividad.
2. Su condición de verificación exige `200` **y** puntaje ≥ 70 sobre `biometric["0"]["1"]`, y una respuesta inesperada no aprueba por descarte.
3. Si cambió `distanceMethodology`, calibró su propio umbral y no reutilizó el 70.
4. Su deserializador indexa los resultados por **cadena** (`"0"`, `"1"`) y tolera que `inferenceConfidence` venga con o sin `code`/`confidence`.
5. Su cliente HTTP tolera cuerpos de error **que no son JSON** (los `500` en texto plano).
6. `operations` tiene exactamente una entrada por imagen.
7. Las imágenes miden al menos 360 × 360 y el JPEG va en calidad ≥ 90.
8. Nunca reintenta un no-match ni un `spoofing: true` con la misma imagen.
9. La api-key vive en su backend, nunca en la app móvil ni en el front-end.
10. Envía un `info` propio por operación y registra el `id` de cada respuesta.
11. `events` queda deshabilitado en producción: la traza es para diagnóstico.

<Card title="Siguiente: Respuestas" icon="list-check" href="/vucs/face-analysis/respuestas">
  La matriz biométrica campo por campo, el veredicto de calidad que cambia de forma y el antispoofing anidado.
</Card>


## Related topics

- [Identity Link API: guía de integración completa](/identity-link/introduccion.md)
- [Changelog de Identity Link API](/identity-link/changelog.md)
- [Antispoofing Facial](/vucs/antispoofing-facial/introduccion.md)
- [Documentación técnica de VU](/index.md)
- [Connection Fingerprint](/vucs/connection-fingerprint/introduccion.md)


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