Skip to main content

​
El recorrido completo

1

Verifique conectividad y credenciales

Un 200 confirma que la URL base y la api-key son correctas. Un 401 significa clave inválida o ambiente equivocado. Evalúe el código de estado, no el cuerpo: los números de versión cambian y no son parte de su contrato.
2

Prepare la imagen

Capture o reciba un JPEG, ajústelo a las dimensiones recomendadas y conviértalo a base64 sin prefijo.
3

Llame a POST /inference

Un único JSON con image, info y logAnonymity.
4

Aplique la regla de decisión

status === 200 && spoofing === false aprueba. Todo lo demás, no.

​
Requisitos de la imagen

Entre 224 × 224 y 640 × 480 no hay error, pero sí menos detección. Varias capas de análisis necesitan resolución para funcionar. Una imagen chica pasa la validación, se procesa y devuelve 200 —con menos capas mirando—. Es la falla silenciosa más cara de esta integración: no la va a ver en los logs, la va a ver en el fraude.
Si su app móvil ya captura a mayor resolución, redimensione en el servidor antes de enviar. Enviar 4 000 × 3 000 píxeles no mejora la detección y sí multiplica el tiempo de respuesta y el tamaño del payload.

​
Convertir a base64

En Linux, -w 0 evita los saltos de línea que base64 inserta cada 76 caracteres. Sin esa bandera la cadena llega partida y el servicio no puede decodificarla.

​
Cuerpo de la solicitud

Siempre envíe un info no vacío con un identificador que le permita reconstruir el caso: número de trámite, id de sesión de onboarding, lo que use su negocio. Vuelve en la respuesta y es lo que conecta una transacción de VU con un usuario en su sistema cuando algo hay que investigar.

​
El campo info en la respuesta

Aquí es donde más integraciones se rompen. info no siempre es del mismo tipo: Resúelvalo en un solo lugar y nunca lea info directamente:
En Java, tipe info como Object, nunca como String. Es la causa número uno de fallas de integración: el mapeo funciona en todas las pruebas —donde info vuelve como cadena— y explota en producción la primera vez que un caso trae diagnóstico y info llega como objeto. Lo mismo aplica a cualquier deserializador estricto.

​
Timeouts y reintentos

Nunca reintente una respuesta con spoofing: true. Es un veredicto, no un error. Reintentar hasta obtener otro resultado convierte su control antifraude en un generador de falsos aprobados.

​
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: status === 200 && spoofing === false.
  2. Ninguna rama decide sobre errorCode, values, confidence o info.
  3. info se lee a través de un único resolutor que contempla objeto, string y null.
  4. En lenguajes tipados, info está declarado como tipo dinámico u Object.
  5. imageQuality y sus subcampos se leen como opcionales; ninguna clave se asume presente.
  6. Las imágenes salen a 640 × 480 con calidad JPEG ≥ 95.
  7. Existe una validación previa que descarta imágenes menores a 224 × 224 antes de gastar una llamada.
  8. El base64 se genera sin prefijo data: y sin saltos de línea.
  9. El timeout está en 30 s.
  10. Los reintentos están limitados a 2 y solo para 499 y 500 no deterministas.
  11. El id de cada transacción queda en su log, junto con el ambiente y la marca de tiempo.
  12. La api-key vive solo en el backend y está en un gestor de secretos, no en el código.
  13. El equipo sabe que 422 No Face Detected es un problema de captura y que 422 Bad request es un problema de código.

Respuestas

El siguiente paso: qué significa cada campo de la respuesta y cómo leer el diagnóstico.
Última modificación el 9 de septiembre de 2026