Skip to main content
POST
/
api
/
kyc
/
biometric
Verificação biométrica
curl --request POST \
  --url http://api.gu1.ai/api/kyc/biometric \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_image": "<string>",
  "entityId": "<string>",
  "externalEntityId": "<string>"
}
'

​
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 ou externalEntityId). 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 funcionaO serviço consulta as sessões KYC aprovadas (criadas via validação por sessão) 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

Você pode enviar a solicitação em qualquer um dos formatos:
  • multipart/form-data: campos do form userImage ou user_image (arquivo ou base64) e opcionais entityId, externalEntityId.
  • application/json: body com user_image (string base64) e opcionais entityId, externalEntityId.
É obrigatório enviar pelo menos um de entityId ou externalEntityId 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

​
user_image
string
required
Imagem do rosto em base64 (com ou sem prefixo data:image/...;base64,). Em multipart use o campo userImage ou user_image e envie um arquivo ou string base64. Formatos: JPEG, PNG, WebP, TIFF. Máx. 5MB.
​
entityId
string
UUID da entidade pessoa na Gu1. É obrigatório enviar entityId ou externalEntityId.
​
externalEntityId
string
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 entityId ou externalEntityId.

​
Resposta

​
Sucesso (200 OK)

CampoTipoDescrição
matchbooleantrue se o rosto coincidiu com pelo menos uma validação KYC aprovada na sua conta para esta entidade (ver nota abaixo).
approvedSessionIdsstring[]IDs de sessão do serviço de verificação considerados correspondências aprovadas.
matchedKycValidationIdsstring[]IDs das validações KYC na sua conta que correspondem a essas sessões e têm status approved na nossa base de dados.
Só é retornado match quando a validação existe na nossa base com status approved. Se uma sessão foi aprovada pelo serviço de verificação mas nós a rejeitamos depois (ex.: por inconsistência com RENAPER), na nossa base ela constará como rejeitada e não será considerada match. | faceSearch | object | Resumo: status, totalMatches, approvedMatchesCount, requestId (para suporte). | Exemplo: 
{
  "match": true,
  "approvedSessionIds": ["session-abc-123"],
  "matchedKycValidationIds": ["550e8400-e29b-41d4-a716-446655440000"],
  "faceSearch": {
    "status": "Approved",
    "totalMatches": 1,
    "approvedMatchesCount": 1,
    "requestId": "req_xyz"
  }
}

​
Exemplo de solicitação

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);

​
Respostas de erro

CódigoHTTPSignificado
NOT_CONFIGURED403Credenciais de validação KYC por sessão não configuradas na organização.
NOT_ENABLED403Integração de validação KYC por sessão não está ativada para esta organização.
INVALID_REQUEST400Body ausente ou inválido (ex.: falta user_image ou não foi enviado entityId nem externalEntityId).
NOT_FOUND404Nenhuma entidade encontrada para o externalEntityId informado nesta organização.
UNAUTHORIZED401Autenticação inválida ou ausente.
VERIFICATION_FAILED500Verificaçã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

Criar validação KYC

Iniciar uma verificação por sessão

Face Match (Documento + Selfie)

Comparar duas imagens em uma chamada