Skip to main content
POST
/
api
/
kyc
/
biometric
/
sessions
Sessão biométrica incorporada
curl --request POST \
  --url http://api.gu1.ai/api/kyc/biometric/sessions \
  --header 'Authorization: Bearer <token>'

​
Visão geral

A biometria incorporada revalida se quem conclui o fluxo é a mesma pessoa do KYC aprovado. Diferente do check biométrico síncrono, a Gu1 devolve sessionUrl com UI hospedada. Incorpore em iframe (ou redirecione) para captura com liveness controlado.
Use status da API ou do webhook como resultado biométrico. A Gu1 gere o ciclo completo da sessão e pode definir rejected após políticas da organização (cruzamento entre entidades, limiares de face match).

​
Pré-requisitos

  1. KYC aprovado na Gu1 para a entidade pessoa.
  2. Retrato de referência disponível a partir desse KYC.
  3. KYC habilitado na organização (mesma API key e permissões da validação por sessão). A Gu1 provisiona a configuração interna de captura incorporada; integradores não definem workflows nem credenciais extras. Se a org ainda não foi habilitada, o create pode retornar BIOMETRIC_WORKFLOW_NOT_CONFIGURED (400) — contate a equipe Gu1.
  4. Gu1 Biometria ativo na organização (global_gueno_biometric_kyc). Se não estiver habilitado, o create retorna NOT_ENABLED (403) — solicite ativação à Gu1.

​
Criar sessão

POST /api/kyc/biometric/sessions — entityId, webhookUrl opcional, callback, language. Fluxo face match (liveness + comparação com retrato do KYC aprovado; NO_PORTRAIT se faltar selfie).

​
Incorporar

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

​
Status e webhooks

Consulte GET .../sessions/:id, GET .../entities/:entityId/current (sessão atual = última com status: approved; tentativas mais novas em rejected, pending ou in_progress não substituem uma aprovação anterior; o listado por entidade inclui currentSessionId), POST .../sessions/:id/sync, POST .../sessions/:id/cancel (cancela pending/in_progress → cancelled), GET .../sessions/:id/media?key= (imagens em decision). In Review aparece como in_progress na Gu1 até o veredito final. Eventos biometric.session_* — eventos biométricos.