> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Começar

> Conheça a Biometria Facial, seus usos, requisitos e modos de referência.

A **Biometria Facial** verifica se a pessoa diante da câmera corresponde a uma imagem de referência. Diferente da [biometria completa](https://docs.jelou.ai/pt/guias/integracoes/identidade/conectar-biometria.md), ela não captura nem analisa um documento de identidade.

> [!NOTE]
>
> A experiência usa prova de vida e comparação facial. A imagem de referência pode vir do Registro Civil do Equador ou do cliente, conforme o modo configurado.

## O que inclui

\| Etapa | O que faz |
\|---|---|---|
\| **Prova de vida** | Confirma que há uma pessoa real diante da câmera. |
\| **Comparação facial** | Compara a selfie com a imagem de referência e calcula a similaridade. |

### ✅ Checklist para começar sem bloqueios

* Forneça uma URL pública dos Termos e Condições.
* Habilite as permissões de câmera do usuário.
* No modo **Foto do Registro Civil**, opere no Equador e tenha documento e código dactilar.
* No modo **Foto fornecida no fluxo**, forneça `referenceImageUrl` pelo nó Biometria ou Memory.
* Mantenha a imagem disponível enquanto a sessão estiver válida.
* A busca biométrica 1:N não faz parte deste produto.

## Modos de referência

> [accordion] government
>
> Consulta a foto do Registro Civil usando o documento de identidade e o código dactilar do usuário. Disponível apenas no Equador.
>
> * Configure `maxGovValidationAttempts`; o valor padrão da webview é 3.
> * O usuário informa exatamente 10 dígitos do documento.
> * O código dactilar aceita de 6 a 10 caracteres alfanuméricos e é convertido para maiúsculas.
> * A câmera abre somente quando o Registro Civil retorna a foto da pessoa.

> [accordion] client
>
> Compara a selfie com a imagem enviada pelo cliente por meio de `referenceImageUrl`. Disponível em qualquer país.
>
> * A URL pode vir do mesmo fluxo ou de outro fluxo por meio do **Memory**.
> * A imagem deve continuar disponível enquanto a sessão estiver ativa.
> * O usuário não informa dados nem vê etapas de documento.

## Configuração

Configure o modo no **nó Biometria** ao criar a sessão.

| Campo | Modo | Descrição |
| - | - | - |
| `faceReferenceSource` | Ambos | `government` ou `client`. Se omitido, funciona como biometria completa. |
| `maxGovValidationAttempts` | `government` | Número máximo de tentativas para validar o documento. Usa 3 quando omitido. |
| `referenceImageUrl` | `client` | URL da imagem de referência, do fluxo atual ou do Memory. |
| `companySettings.facematchThreshold` | Ambos | Limite de similaridade para aprovar a comparação facial. |

O modo fica fixo quando a sessão é criada. Alterações posteriores não afetam sessões existentes.

## Como funciona

**1. Crie a sessão**

O nó Biometria cria a sessão no **identity-service** com o modo escolhido e, em `client`, com a imagem de referência.

**2. Abra o link**

A webview lê o modo em `/flow-state` e, como alternativa, em `details.faceReferenceSource`.

**3. Valide a referência**

Em `government`, o usuário informa o documento e o código dactilar antes da selfie. Em `client`, o nó já enviou a imagem.

**4. Faça a prova de vida**

A única captura é uma selfie guiada com prova de vida. A webview usa `biometricFlow = ['liveness']`.

**5. Compare os rostos**

O **identity-service** compara a selfie aprovada com a imagem de referência. O provedor é AWS Rekognition.

**6. Entregue o resultado**

A Jelou envia o webhook para o fluxo ou cliente e retorna o usuário ao WhatsApp ou `callbackUrl`.

## Entradas e saídas

### Webhook final

* `document_response.document_check` chega omitido com `reason: "not_in_biometric_flow"`.
* Em `government`, `gov_response` inclui o resultado do Registro Civil.
* Em `client`, `gov_response` chega omitido com `reason: "face_reference_client"`.
* `facematch_result` usa minúsculas (`approved` ou `declined`); os resultados de prova de vida e governo usam maiúsculas.
* Quando a comparação falha, `facematch_response` adiciona `imageDocumentUrl` e `imageLivenessUrl`.

## Experiência do usuário

> [tab] government — Equador
>
> 1. Tela inicial e termos.
> 2. O usuário informa documento e código dactilar.
> 3. Faz a selfie com prova de vida.
> 4. Vê a comparação facial sem etapas de OCR, recaptura ou manipulação.
> 5. Recebe o resultado e retorna ao WhatsApp ou `callbackUrl`.

> [tab] client
>
> 1. Tela inicial e termos.
> 2. Faz a selfie sem informar dados nem ver informações de documentos.
> 3. A identidade é validada.
> 4. Recebe o resultado e retorna ao WhatsApp ou `callbackUrl`.

## Limites e considerações

* A imagem de `client` deve permanecer disponível durante toda a sessão; uma URL assinada expirada retorna `reference_image_unavailable`.
* O fluxo não captura documentos, executa OCR nem detecta recaptura ou manipulação documental.
* A busca biométrica 1:N não faz parte deste produto.
* Confirme com a equipe de backend a duração exata da sessão e o formato de `gov_entity_data`.

> [card] [Próximo: Configuração](https://docs.jelou.ai/pt/guias/integracoes/identidade/configuracao-biometria.md)
>
> Configure o nó Biometria e suas saídas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.