Skip to main content
POST
Verificação biométrica

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

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

ou, para multipart:
A organização é obtida do contexto de autenticação; não é necessário enviar X-Organization-Id.

Parâmetros do body

user_image
file | string
required
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.
entityId
string
UUID da entidade pessoa na Gu1. É obrigatório enviar pelo menos um de entityId, entityExternalId ou entityTaxId.
entityExternalId
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 pelo menos um identificador de entidade.
externalEntityId
string
Alias obsoleto de entityExternalId. Ainda aceito em POST /api/kyc/biometric por compatibilidade. Prefira entityExternalId em novas integrações.
entityTaxId
string
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)

Exemplo:

Exemplo de solicitação

Respostas de erro

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