> ## 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 ID Analysis
> Cómo armar el flujo frente → dorso, preparar las imágenes, usar el catálogo de templates y validar la integración antes de producción.
## El recorrido completo
```bash theme={null}
curl -i -X GET "$BASE_URL/version" -H "Api-Key: $VU_ID_ANALYSIS_API_KEY"
```
`/version` no exige api-key, así que separa un problema de red (falla `/version`) de uno de credenciales (falla solo `/front` con `401`). Evalúe el código de estado, no el cuerpo.
Foto del documento completo, apoyado, sin reflejos, en base64 sin prefijo y de al menos 480 × 480 píxeles.
El `uuid` de la respuesta es el enganche con el dorso y el dato que soporte necesita. Guárdelo siempre.
Con la foto del dorso y el `uuid` del frente como `relatedUuid`.
`200` + `"Operation end successfully."` + `id` identificado — y en el dorso, `frontBackTemplateValidation === true`.
## Cuerpo de la solicitud
```json theme={null}
{
"info": "onboarding-12345",
"image": "/9j/4AAQSkZJRgABAQ...",
"relatedUuid": "e2084653-7268-4748-9b80-a0da6a22a875"
}
```
| Campo | Tipo | Descripción |
| - | - | - |
| `info` | string | Su referencia de negocio, de **2 a 256 caracteres**. Obligatorio. Vuelve tal cual en la respuesta. |
| `image` | string | La foto en base64 sin prefijo `data:`. Obligatorio. Mínimo **480 × 480 px**; más de 1920 px de lado se reduce automáticamente. |
| `relatedUuid` | string | El `uuid` del `/front` previo. **Obligatorio en `/back`, prohibido en `/front`** — ver la advertencia. |
| `documentId` | string | Pista del tipo de documento (p. ej. `VU-ARG-ID-04`). Acota y acelera la inferencia cuando ya sabe qué documento espera. |
| `possibleCountries` | string\[] | Códigos de país de 3 letras (`["ARG"]`) para acotar la identificación. |
| `antiSpoofingDocument` | boolean | Analiza si la imagen es una captura de un documento real o una reproducción. Agrega `security.*`. |
| `antiSpoofingFaceInDocument` | boolean | Analiza si la foto carnet del documento fue adulterada. Agrega `face.isSpoofing`. |
| `strictBorderMode` | boolean | Rechaza con `400` los documentos demasiado pegados al borde de la foto. |
| `logAnonymity` | boolean | Las imágenes no se persisten en el registro de transacciones de VU. La respuesta no cambia. |
| `events` | boolean | Agrega la traza de ejecución, sin imágenes. Útil para diagnóstico. |
**Nunca envíe `relatedUuid` en `/front`.** Ese campo es exclusivo de `/back`; incluirlo en `/front` produce un error `500` del servicio, no un `4xx` descriptivo. Y a pesar de lo que sugiere el mensaje de error de `/back`, **lo único que satisface el requisito es el `uuid` de un `/front` previo** — `documentId` no lo reemplaza.
## Requisitos de la imagen
| Aspecto | Valor | Qué pasa si no se cumple |
| - | - | - |
| Mínimo duro | 480 × 480 | `400` con `Image is too small {alto}x{ancho}, min size allowed 480x480.` |
| Máximo útil | 1920 px de lado | Por encima se reduce automáticamente; enviar más no mejora la lectura. |
| Encuadre | Documento completo, apoyado, sin reflejos | Brillos sobre el laminado y dedos tapando campos son la primera causa de campos vacíos y de `Cant get document fields`. |
| Formato | JPEG (calidad ≥ 90) o PNG | La compresión agresiva degrada el OCR. |
| Codificación | base64 sin prefijo `data:` y sin saltos de línea | `400` con `Image is not a valid, …`. |
### Convertir a base64
```powershell Windows theme={null}
[Convert]::ToBase64String([IO.File]::ReadAllBytes("frente.jpg")) | Set-Content -NoNewline frente.b64
```
```bash Linux theme={null}
base64 -w 0 frente.jpg > frente.b64
```
```bash macOS theme={null}
base64 -i frente.jpg -o frente.b64
```
## El enganche frente → dorso
```mermaid theme={null}
sequenceDiagram
participant B as Su backend
participant IDA as ID Analysis
B->>IDA: POST /front { info, image }
IDA-->>B: 200 { uuid, id, front, hasBackSide: true }
B->>B: Guarda uuid
B->>IDA: POST /back { info, image, relatedUuid: uuid }
IDA-->>B: 200 { front, back { frontBackTemplateValidation }, crossMatchConfidence }
B->>B: Decide con las validaciones
```
**Si el dorso viaja inmediatamente después del frente**, un `400 Bad relatedUuid` ocasional puede significar que el registro del frente aún no estaba disponible. Espere unos segundos y reintente una sola vez antes de tratarlo como error definitivo.
## El catálogo de templates
Los campos que trae `viz` **varían por tipo de documento**. La referencia autoritativa es el propio catálogo del servicio:
| Consulta | Devuelve |
| - | - |
| `GET /listTemplates` | El arreglo de identificadores soportados. Formato `VU---`; tipos: `ID` cédula/DNI, `IDF` documento de extranjero, `PA` pasaporte, `DL` licencia de conducir. **La respuesta es un arreglo JSON directo**, sin envoltorio. |
| `GET /{templateId}/details` | El contrato del template: `front.fields` / `back.fields`, `hasMrz`, `hasBarcode`, `hasFace`, el tipo de barcode y qué pares de fuentes cruza la validación. |
| `GET /{templateId}/images` | Imágenes de muestra **anonimizadas** (base64), para probar sin un documento real. `front` y `back` son arreglos de un elemento. |
Consulte `/details` en tiempo de integración para saber qué campos programar por documento, y pruebe con las imágenes de `/images` antes de usar documentos reales. Si su flujo es «DNI argentino», envíe `documentId` o `possibleCountries`: acota la inferencia, la acelera y elimina falsas identificaciones.
## Timeouts y reintentos
| Parámetro | Valor | Motivo |
| - | - | - |
| Timeout | 30 s | El tiempo típico por cara es de 2 a 3 segundos; el antispoofing agrega llamadas internas. |
| Reintentos | Máximo 2, con backoff | Solo para `5xx` esporádicos — más el caso especial del `Bad relatedUuid` inmediato (una espera y un reintento). |
| Qué **no** reintentar | `400`, `401`, `404`, `422` | El problema está en su solicitud o su captura; reintentar da el mismo error. |
| Tampoco | Un `200` que no aprueba | «Documento ilegible» o «dorso cruzado» se resuelven con otra captura o revisión manual, no repitiendo la llamada. |
**Las respuestas son pesadas — alrededor de 1 MB.** La imagen normalizada del documento y el recorte del rostro viajan siempre en los `200`. Dimensione buffers y no persista respuestas completas sin necesidad.
## Antes de salir a producción
Una integración está lista cuando puede responder que sí a todo esto:
1. La decisión está escrita en positivo: `200` **y** `message: "Operation end successfully."` **y** `id !== "unknown"` — y en el dorso, `frontBackTemplateValidation === true`.
2. Probó la foto sin documento y su sistema pide otra captura en vez de aceptar campos vacíos.
3. Probó el dorso de otro documento y su sistema lo rechaza.
4. `relatedUuid` solo se envía en `/back`, y siempre con el `uuid` de un `200` de `/front` — nunca el de un cuerpo de error.
5. Las capturas cumplen 480 × 480 y el base64 va sin prefijo `data:` y sin saltos de línea.
6. Los logs no persisten cuerpos de error crudos —el `detail` de los `422` contiene la solicitud completa, imagen incluida— ni respuestas completas con imágenes.
7. El timeout está en 30 s y los reintentos limitados a 2, solo para `5xx` esporádicos.
8. El `uuid` de cada transacción queda en su log, junto con el ambiente y la marca de tiempo.
9. La api-key vive solo en el backend y está en un gestor de secretos, no en el código.
10. El equipo sabe que `200 Cant get document fields` es un problema de captura, no un bug.
El siguiente paso: la estructura de `front` y `back`, las validaciones cruzadas y los dos `200` que no aprueban.
## Related topics
- [ID Analysis](/vucs/id-analysis/introduccion.md)
- [Integrar Antispoofing Facial](/vucs/antispoofing-facial/integracion.md)
- [Integrar Connection Fingerprint](/vucs/connection-fingerprint/integracion.md)
- [Guía de integración](/vucs/face-analysis/integracion.md)
- [Inicio rápido: tu primera verificación de identidad](/quickstart.md)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.