Guía de integración

El flujo en cuatro pasos

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.

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.

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.

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.

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:

[Convert]::ToBase64String([IO.File]::ReadAllBytes('C:\ruta\selfie.jpg')) | Set-Clipboard

base64 -w0 selfie.jpg

base64 -i selfie.jpg | pbcopy

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.

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.

Los tres modos de comparar

// 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 }

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.

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

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

Siguiente: Respuestas

La matriz biométrica campo por campo, el veredicto de calidad que cambia de forma y el antispoofing anidado.

Empezar aquí

ID Analysis

Face Analysis

Antispoofing Facial

Connection Fingerprint

El flujo en cuatro pasos

Requisitos de imagen

El cuerpo de la solicitud

Los tres modos de comparar

Un lote no tolera fallas parciales

Timeouts y reintentos

Antes de salir a producción

Siguiente: Respuestas

​El flujo en cuatro pasos

​Requisitos de imagen

​El cuerpo de la solicitud

​Los tres modos de comparar

​Un lote no tolera fallas parciales

​Timeouts y reintentos

​Antes de salir a producción

Siguiente: Respuestas

El flujo en cuatro pasos

Requisitos de imagen

El cuerpo de la solicitud

Los tres modos de comparar

Un lote no tolera fallas parciales

Timeouts y reintentos

Antes de salir a producción