> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Verificação biométrica
> Valide uma imagem de rosto contra sessões KYC previamente aprovadas usando a API KYC da gu1 para reautenticação e verificação de identidade.
## Resumo
O serviço **Biométrico** da Gu1 verifica se uma imagem de rosto corresponde a uma pessoa que **já concluiu uma validação KYC aprovada** na sua organização. Você envia uma única imagem do rosto e a entidade a verificar (por `entityId`, `entityExternalId` ou `entityTaxId`). A API compara esse rosto com os dados biométricos armazenados em **sessões de validação por sessão já aprovadas** para essa entidade. Se o rosto coincidir com alguma dessas sessões aprovadas, a resposta indica match e retorna os IDs das validações KYC associadas.
**Como funciona**
O serviço consulta as sessões KYC aprovadas (criadas via [validação por sessão](/pt/use-cases/kyc/create-validation)) para a entidade informada. Compara o rosto que você envia com as informações biométricas já armazenadas nessas sessões aprovadas. Nenhuma nova sessão hospedada é iniciada—é uma verificação pontual contra dados existentes.
## Pré-requisitos
Para este endpoint funcionar, sua organização precisa ter a **validação KYC por sessão** configurada:
1. **Integração de validação por sessão ativada**: A integração usada para validação por sessão (ex.: “Gu1 KYC” / validação por sessão) deve estar **ativada** para sua organização (ex.: no Marketplace / Integrações).
2. **Credenciais configuradas**: A **API key** (e o webhook secret) dessa integração de **validação por sessão** deve estar configurada nas configurações KYC da organização. O endpoint Biométrico usa as mesmas credenciais da validação por sessão para realizar a verificação.
Se essas credenciais não estiverem configuradas ou a integração não estiver ativada, a API retorna **403** (`NOT_ENABLED` ou `NOT_CONFIGURED`).
O serviço Biométrico é um serviço da Gu1. Toda a verificação é executada em nossa infraestrutura; nenhum nome de provedor externo é exposto nas respostas ou nos erros.
## Solicitação
### Endpoint
```
POST https://api.gu1.ai/api/kyc/biometric
```
### Content-Type
Aceita **`multipart/form-data`** ou **`application/json`**.
**Multipart** — envie a imagem do rosto de uma destas formas (igual ao Face Match / ID Verification):
1. **Como arquivo**: campo `userImage` ou `user_image` (recomendado).
2. **Como string base64**: mesmos nomes de campo com a imagem em base64 (com ou sem prefixo `data:image/...;base64,`).
Se a imagem estiver ausente (sem arquivo nem base64), a API retorna **400**.
**JSON** — envie `user_image` ou `userImage` como base64, data URL ou URL http(s) para o servidor buscar a imagem. Identificadores de entidade: `entityId`, `entityExternalId` e/ou `entityTaxId`.
É obrigatório enviar **pelo menos um** de `entityId`, `entityExternalId` ou `entityTaxId` para a API saber contra qual entidade verificar.
### Headers
```
Authorization: Bearer SUA_API_KEY
Content-Type: application/json
```
ou, para multipart:
```
Authorization: Bearer SUA_API_KEY
Content-Type: multipart/form-data; boundary=----...
```
A organização é obtida do contexto de autenticação; não é necessário enviar `X-Organization-Id`.
### Parâmetros do body
Imagem do rosto. **Multipart:** campo `userImage` ou `user_image` como **arquivo** ou **string base64** (com ou sem prefixo `data:image/...;base64,`). **JSON:** `user_image` ou `userImage` como base64, data URL ou URL http(s). Formatos: JPEG, PNG, WebP, TIFF. Máx. 5MB.
UUID da entidade pessoa na Gu1. É obrigatório enviar pelo menos um de `entityId`, `entityExternalId` ou `entityTaxId`.
Seu próprio identificador da entidade (ID externo). Se você não enviar `entityId`, a API resolve a entidade por organização + `externalId`. É obrigatório enviar pelo menos um identificador de entidade.
**Alias obsoleto** de `entityExternalId`. Ainda aceito em `POST /api/kyc/biometric` por compatibilidade. Prefira `entityExternalId` em novas integrações.
Identificação fiscal da entidade (CUIT, CPF, RFC, etc.). Se você não enviar `entityId` nem `entityExternalId`, a API resolve a entidade por organização + `tax_id` normalizado (ignora hífens, pontos e outros caracteres de formatação). É obrigatório enviar pelo menos um identificador de entidade.
## Resposta
### Sucesso (200 OK)
| Campo | Tipo | Descrição |
| ------------------------- | --------- | ----------------------------------------------------------------------------------------------- |
| `match` | boolean | `true` se o rosto coincide com pelo menos uma validação KYC **approved** desta entidade na Gu1. |
| `matchedSessionIds` | string\[] | Session IDs das validações approved que deram match. |
| `matchedKycValidationIds` | string\[] | IDs dessas validações KYC na Gu1. |
| `faceSearch` | object | Resumo: `totalMatches`, `requestId` (para suporte). |
**Exemplo:**
```json theme={null}
{
"match": true,
"matchedSessionIds": ["session-abc-123"],
"matchedKycValidationIds": ["550e8400-e29b-41d4-a716-446655440000"],
"faceSearch": {
"totalMatches": 1,
"requestId": "req_xyz"
}
}
```
## Exemplo de solicitação
```javascript JSON body (entityTaxId) theme={null}
const response = await fetch('https://api.gu1.ai/api/kyc/biometric', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
user_image: 'data:image/jpeg;base64,/9j/4AAQ...',
entityTaxId: '20-41873887-2',
}),
});
const result = await response.json();
console.log('Match:', result.match, 'KYC validations:', result.matchedKycValidationIds);
```
```javascript JSON body theme={null}
const response = await fetch('https://api.gu1.ai/api/kyc/biometric', {
method: 'POST',
headers: {
'Authorization': 'Bearer SUA_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
user_image: 'data:image/jpeg;base64,/9j/4AAQ...',
entityId: '550e8400-e29b-41d4-a716-446655440000',
}),
});
const result = await response.json();
console.log('Match:', result.match, 'Validações KYC:', result.matchedKycValidationIds);
```
```javascript Multipart (arquivo) theme={null}
const form = new FormData();
form.append('userImage', imageFile);
form.append('entityId', '550e8400-e29b-41d4-a716-446655440000');
const response = await fetch('https://api.gu1.ai/api/kyc/biometric', {
method: 'POST',
headers: { 'Authorization': 'Bearer SUA_API_KEY' },
body: form,
});
const result = await response.json();
```
```curl cURL (multipart) theme={null}
curl -X POST https://api.gu1.ai/api/kyc/biometric \
-H "Authorization: Bearer SUA_API_KEY" \
-F "userImage=@selfie.jpg" \
-F "entityId=550e8400-e29b-41d4-a716-446655440000"
```
## Respostas de erro
| Código | HTTP | Significado |
| --------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------- |
| `NOT_CONFIGURED` | 403 | Credenciais de validação KYC por sessão não configuradas na organização. |
| `NOT_ENABLED` | 403 | Integração de validação KYC por sessão não está ativada para esta organização. |
| `INVALID_REQUEST` | 400 | Body ausente ou inválido (ex.: falta `user_image` ou nenhum de `entityId`, `entityExternalId`, `entityTaxId` foi enviado). |
| `NOT_FOUND` | 404 | Nenhuma entidade encontrada para o `entityId`, `entityExternalId` ou `entityTaxId` informado nesta organização. |
| `UNAUTHORIZED` | 401 | Autenticação inválida ou ausente. |
| `VERIFICATION_FAILED` | 500 | Verificação não pôde ser concluída; tentar novamente ou contatar o suporte. |
## Relação com o KYC por sessão
* **Validação por sessão** (`POST /api/kyc/validations`): Cria uma sessão KYC, fornece uma URL hospedada ao usuário e armazena o resultado (incluindo dados biométricos) ao concluir o fluxo. Essas sessões são as que o endpoint Biométrico usa para comparar.
* **Biométrico** (`POST /api/kyc/biometric`): Você envia uma imagem de rosto e a API verifica se coincide com alguma sessão **já aprovada** para essa entidade. Use quando precisar re-verificar a mesma pessoa (ex.: no login ou em uma nova ação) sem iniciar uma nova sessão.
Ambos usam as mesmas credenciais da organização para validação KYC por sessão. Se essas credenciais não estiverem configuradas, o endpoint Biométrico não pode ser executado.
## Próximos passos
Iniciar uma verificação por sessão
Comparar duas imagens em uma chamada