Verificação biométrica
Biométrico
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.
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 (porentityId, 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:- 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).
- 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.
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
Aceitamultipart/form-data ou application/json.
Multipart — envie a imagem do rosto de uma destas formas (igual ao Face Match / ID Verification):
- Como arquivo: campo
userImageouuser_image(recomendado). - Como string base64: mesmos nomes de campo com a imagem em base64 (com ou sem prefixo
data:image/...;base64,).
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
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)
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.
Próximos passos
Criar validação KYC
Iniciar uma verificação por sessão
Face Match (Documento + Selfie)
Comparar duas imagens em uma chamada