Skip to main content
POST
/
api
/
kyc
/
biometric
/
sessions
Sesión biométrica embebida
curl --request POST \
  --url http://api.gu1.ai/api/kyc/biometric/sessions \
  --header 'Authorization: Bearer <token>'

​
Resumen

Biometría embebida permite re-verificar que quien completa un flujo es la misma persona que aprobó el KYC. A diferencia del chequeo biométrico síncrono, acá Gu1 devuelve un sessionUrl con UI hospedada de captura. Tu app lo embebe en un iframe (o redirige) para que el liveness ocurra en un entorno controlado.
Usá status de la API o del webhook como resultado biométrico. Gu1 gestiona el ciclo completo de la sesión y puede devolver rejected tras políticas de la organización (cruces entre entidades, umbrales de face match).

​
Requisitos

  1. KYC aprobado en Güeno para la entidad persona.
  2. Retrato de referencia disponible desde ese KYC.
  3. KYC habilitado en tu organización (misma API key y permisos que la validación por sesión). La configuración interna de captura biométrica embebida la provisiona el equipo Gu1; como integrador no configurás workflows ni credenciales adicionales. Si la org aún no fue habilitada, POST /api/kyc/biometric/sessions puede responder BIOMETRIC_WORKFLOW_NOT_CONFIGURED (400) — contactá a tu contacto Gu1.
  4. Gu1 Biometría activo para tu organización (global_gueno_biometric_kyc). Si no está habilitado, la API responde NOT_ENABLED (403) — solicitá la activación a Gu1.

​
Crear sesión

POST /api/kyc/biometric/sessions Parámetros clave: entityId (requerido), webhookUrl (opcional, callback HTTPS en estados terminales), callback, language. Flujo face match (liveness + comparación contra retrato del KYC aprobado; NO_PORTRAIT si falta selfie). Respuesta 201: id, sessionUrl, iframeAllow, hostedSessionId (ID de sesión hospedada), status: pending.

​
Embeber

<iframe
  src="{{ sessionUrl }}"
  style="width: 100%; height: 700px; border: none;"
  allow="{{ iframeAllow }}"
></iframe>

​
Consultar estado

  • GET /api/kyc/biometric/sessions/:id
  • GET /api/kyc/biometric/entities/:entityId/current — sesión actual = última sesión con status: approved (por completedAt). Nunca es pending, in_progress, rejected, expired ni abandoned. Si iniciás una validación nueva y expira sin aprobarse, no pasa a ser current; si ya había una aprobada anterior, sigue siendo esa. Sin ninguna aprobada en el historial, current responde 404. El listado por entidad incluye currentSessionId con la misma regla.
  • POST /api/kyc/biometric/sessions/:id/sync
  • POST /api/kyc/biometric/sessions/:id/cancel — cancela manualmente sesiones pending o in_progress (marca cancelled en Gu1; no reemplaza la sesión actual aprobada).
  • GET /api/kyc/biometric/sessions/:id/media?key= — imágenes persistidas referenciadas en decision.
La plataforma puede reportar In Review durante la revisión de la captura; en Gu1 eso se refleja como in_progress hasta el veredicto final (approved o rejected). Solo los estados terminales de resultado cuentan para definir la sesión actual.

​
Webhooks

  • webhookUrl por request — si lo enviás al crear la sesión.
  • Webhooks de organización — eventos biometric.session_*. Ver eventos biométricos.
Para autenticación reforzada en login o step-up, preferí sesiones embebidas frente al endpoint síncrono.