SmartEnroll — Guía de API

Tras completar el KYC de SmartEnroll hospedado, usa esta guía para integrar resultados en tu backend: scores de comparación facial, vitalidad, webhooks y los endpoints relevantes. Es un complemento a la documentación de producto—no sustituye la API de SmartEnroll autoalojado.

Resumen del flujo

flowchart LR
  hosted[SmartEnroll_hospedado]
  compare[Comparacion_facial]
  webhook[Webhook_face_verification_compare]
  getAR[GET_app_registrations_populate]
  hosted --> compare
  compare --> webhook
  compare --> getAR
  getAR --> scores[score_passed_umbral]

1. El usuario final completa documento + biometría en el flujo hospedado.
2. Verifik ejecuta la comparación facial (selfie vs cara del documento) con los umbrales de tu proyecto.
3. Recibes un webhook (si está configurado) y/o consultas el app registration con populates.
4. Aplicas tus reglas de negocio con score, passed y compare_min_score.

Leer scores de comparación facial

No existe un GET /v2/face-verifications/:id público. Los scores viven en el FaceVerification enlazado desde el app registration.

GET https://api.verifik.co/v2/app-registrations/{id}?populates[]=compareFaceVerification

Campos útiles en el objeto populado:

Campo	Significado
compareFaceVerification.result.score	Score de similitud (0–1)
compareFaceVerification.result.passed	Si el score cumplió el umbral efectivo
compareFaceVerification.result.compare_min_score	Umbral usado en esa comparación
compareFaceVerification.comparedAt	Cuándo se ejecutó la comparación

TTL: Los registros FaceVerification expiran en unos 90 días en producción (10 días en desarrollo). Tras expirar, compareFaceVerification puede venir vacío aunque el app registration siga existiendo.

Consulta también la documentación de app registrations en Resources (Get App Registration).

Populates útiles

Conjunto habitual para un snapshot completo del enrollment:

project, projectFlow, emailValidation, phoneValidation, biometricValidation, documentValidation, person, face, documentFace, compareFaceVerification, informationValidation

Endpoints clave

Endpoint	Propósito
POST /v2/face-recognition/liveness	Detección de vitalidad estándar
POST /v2/face-recognition/liveness-score	Vitalidad enfocada en el puntaje (misma facturación que /liveness)
POST /v2/face-recognition/compare	Comparación facial 1:1 (API directa)
POST /v2/face-recognition/compare-with-liveness	Comparar y luego vitalidad (secuencial)
POST /v2/face-recognition/compare/app-registration	Comparación del flujo hospedado: usa appRegistrationId de la sesión; gallery/probe desde caras guardadas; cuerpo vacío {} válido; umbral del project flow
GET /v2/app-registrations/:id	Leer el enrollment + popular scores
POST /v2/app-registrations/:id/resend-link	Generar una URL hospedada de continuación para un enrollment incompleto
POST /v2/biometric-validations/app-registration	Paso biométrico / vitalidad en la sesión hospedada
POST /v2/document-validations/app-registration	Captura / validación de documento en la sesión hospedada
POST /v2/identity-images/appRegistration	Guardar imágenes de identidad (face, documentFace, …)

Para una UI totalmente personalizada, empieza por SmartEnroll autoalojado.

Umbrales de comparación facial

Contexto	Valores
SmartEnroll hospedado / project flow (por defecto)	0.85 (compareMinScore)
SmartEnroll hospedado / project flow (rango permitido)	0.65–0.95
API directa de face-recognition (compare_min_score)	0.67–0.95 (por defecto 0.85 si se omite)

Los retratos impresos en documentos suelen estar desgastados, rayados o a baja resolución. Algunas cédulas colombianas son especialmente pobres, y el mismo problema de calidad puede aparecer en otros países. Un selfie en vivo vs una foto impresa puntúa más bajo que en vivo vs en vivo. Bajar el umbral del proyecto hacia 0.65 reduce rechazos falsos de usuarios genuinos con documentos de mala calidad; también sube el riesgo de falsos aceptados. Conserva 0.85 salvo que veas fallos reales.

cropFace

cropFace en servidor no está soportado en los endpoints de face-recognition compare. Omite el campo (se ignora si se envía). Envía imágenes enfocadas en el rostro o recorta en el cliente antes de llamar a la API.

Webhooks

Cuando el project flow tiene webhook, la comparación facial emite un evento con sufijo face_verification_compare. El type entregado es:

{projectFlow.type}_face_verification_compare

Ejemplo: onboarding_face_verification_compare.

El payload incluye campos del app registration más compareResult (resultado FaceVerification). Inventario completo: Webhooks KYC de Smart Enroll.

Vitalidad / PAD (resumen de producto)

La vitalidad facial de Verifik usa nuestro stack biométrico con detección de ataques de presentación (PAD). La vitalidad está certificada iBeta Level 2 y alineada con ISO 30107 Level 1 y Level 2. Está diseñada para detectar vectores de spoofing comunes como fotos impresas, reproducción de video y máscaras 3D, mediante una verificación de una sola imagen. Detalles: Detección de vitalidad y Puntaje de vitalidad.

Documentación de producto relacionada

• SmartEnroll — configuración del proyecto
• Flujo KYC SmartEnroll — experiencia del usuario final
• Reanudar un enrollment incompleto — continuar el KYC hospedado si el usuario abandonó el flujo
• Revisión KYC admin — UI de revisión e interpretación de scores
• SmartEnroll autoalojado — APIs programáticas de proyecto/flujo

Receta rápida

1. Completa (o espera) el enrollment hospedado.
2. Escucha {type}_face_verification_compare o llama GET /v2/app-registrations/{id}?populates[]=compareFaceVerification.
3. Lee result.score, result.passed y result.compare_min_score.
4. Aplica tus reglas de aprobar / revisar / rechazar (recuerda el TTL de FaceVerification).