Integrar ID Analysis

El recorrido completo

Verifique conectividad y credenciales

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.

Prepare la imagen del frente

Foto del documento completo, apoyado, sin reflejos, en base64 sin prefijo y de al menos 480 × 480 píxeles.

Llame a POST /front y guarde el uuid

El uuid de la respuesta es el enganche con el dorso y el dato que soporte necesita. Guárdelo siempre.

Si hasBackSide es true, llame a POST /back

Con la foto del dorso y el uuid del frente como relatedUuid.

Aplique la regla de decisión

200 + "Operation end successfully." + id identificado — y en el dorso, frontBackTemplateValidation === true.

Cuerpo de la solicitud

{
  "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

[Convert]::ToBase64String([IO.File]::ReadAllBytes("frente.jpg")) | Set-Content -NoNewline frente.b64

base64 -w 0 frente.jpg > frente.b64

base64 -i frente.jpg -o frente.b64

El enganche frente → dorso

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-<país ISO3>-<tipo>-<nn>`; 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:

La decisión está escrita en positivo: 200 y message: "Operation end successfully." y id !== "unknown" — y en el dorso, frontBackTemplateValidation === true.
Probó la foto sin documento y su sistema pide otra captura en vez de aceptar campos vacíos.
Probó el dorso de otro documento y su sistema lo rechaza.
relatedUuid solo se envía en /back, y siempre con el uuid de un 200 de /front — nunca el de un cuerpo de error.
Las capturas cumplen 480 × 480 y el base64 va sin prefijo data: y sin saltos de línea.
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.
El timeout está en 30 s y los reintentos limitados a 2, solo para 5xx esporádicos.
El uuid de cada transacción queda en su log, junto con el ambiente y la marca de tiempo.
La api-key vive solo en el backend y está en un gestor de secretos, no en el código.
El equipo sabe que 200 Cant get document fields es un problema de captura, no un bug.

Respuestas

El siguiente paso: la estructura de front y back, las validaciones cruzadas y los dos 200 que no aprueban.

Empezar aquí

ID Analysis

Face Analysis

Antispoofing Facial

Connection Fingerprint

El recorrido completo

Cuerpo de la solicitud

Requisitos de la imagen

Convertir a base64

El enganche frente → dorso

El catálogo de templates

Timeouts y reintentos

Antes de salir a producción

Respuestas

​El recorrido completo

​Cuerpo de la solicitud

​Requisitos de la imagen

​Convertir a base64

​El enganche frente → dorso

​El catálogo de templates

​Timeouts y reintentos

​Antes de salir a producción

Respuestas

El recorrido completo

Cuerpo de la solicitud

Requisitos de la imagen

Convertir a base64

El enganche frente → dorso

El catálogo de templates

Timeouts y reintentos

Antes de salir a producción