Skip to main content
POST
http://api.gu1.ai
/
api
/
kyc
/
face-match
Face Match (Documento + Selfie)
curl --request POST \
  --url http://api.gu1.ai/api/kyc/face-match \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "documentImage": "<string>",
  "selfieImage": "<string>",
  "entityId": "<string>",
  "vendorData": "<string>"
}
'

​
Resumo

Face Match é um serviço de verificação da Gueno que compara duas imagens: uma selfie (foto atual da pessoa) e uma imagem de referência do documento (por exemplo a foto do documento de identidade). A API retorna se as faces coincidem (mesma pessoa) e uma pontuação de similaridade. Não há sessão hospedada nem detecção de vida em tempo real: você envia as imagens e recebe o resultado em uma única chamada.
Quando usar cada um
  • KYC por sessão (POST /api/kyc/validations): Fluxo completo com URL hospedada, selfie ao vivo, liveness e captura de documento. Ideal para onboarding e fluxos regulados.
  • Face Match (POST /api/kyc/face-match): Você envia duas imagens em Base64 e recebe correspondência + pontuação. Ideal quando você já tem documento e selfie (por exemplo da sua própria aplicação).

​
Pré-requisitos

Antes de usar o Face Match:
  1. Integração Face Match ativada: Sua organização deve ter a integração KYC Face Match ativada (por exemplo no Marketplace / Integrações).
  2. Credenciais configuradas: A API key e o webhook secret da integração Face Match devem estar configurados nas configurações KYC da organização (definido pelo administrador da Gueno).
  3. Limiar (opcional): A pontuação mínima para aprovar (0–100) é configurada em Configurações da organização → KYC (card Face Match). Se não for definido, o padrão é 30. Apenas os administradores da organização podem alterar esse valor.
Face Match é um serviço da Gueno. Toda a verificação é feita em nossa infraestrutura; nenhum nome de provedor externo é exposto nas respostas ou nas mensagens de erro.

​
Solicitação

​
Endpoint

POST https://api.gu1.ai/api/kyc/face-match

​
Headers

{
  "Authorization": "Bearer SUA_API_KEY",
  "Content-Type": "application/json"
}
Se sua conta usa escopo por organização, inclua: 
X-Organization-Id: SEU_ORGANIZATION_ID

​
Parâmetros do Body

​
documentImage
string
required
Imagem de referência (por exemplo a foto do documento) em Base64. Com ou sem prefixo data:image/...;base64,. Formatos: JPEG, PNG, WebP, TIFF. Máx. 5MB por imagem.
​
selfieImage
string
required
Imagem da selfie em Base64. Mesmo formato e limite de tamanho que documentImage.
​
entityId
string
UUID opcional da entidade pessoa a associar a esta verificação. Usado para auditoria e para listar verificações por entidade.
​
vendorData
string
Referência opcional (por exemplo seu ID de usuário) para rastreamento. Armazenada no registro de auditoria.
O pontuação mínima (limiar) usada para decidir correspondência ou não não é enviada na solicitação. Ela é lida da configuração KYC da sua organização (Configurações da organização → KYC → Face Match). A resposta inclui o limiar que foi usado na chamada.

​
Resposta

​
Resposta de sucesso (200 OK)

CampoTipoDescrição
matchbooleanSe as faces foram consideradas coincidentes (pontuação ≥ limiar).
scorenumberPontuação de similaridade 0–100.
statusstring"approved" | "declined" | "in_review".
verificationIdstringID do registro de auditoria em face_match_verifications (suporte e listagem).
scoreDeclineThresholdnumberO limiar (0–100) que foi usado nesta verificação (configuração da org).
requestIdstring (opcional)ID interno da solicitação (suporte).
warningsstring[] (opcional)Avisos da verificação.
Exemplo: 
{
  "match": true,
  "score": 85.5,
  "status": "approved",
  "verificationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "scoreDeclineThreshold": 30,
  "requestId": "req_xyz",
  "warnings": []
}

​
Exemplo de solicitação

const response = await fetch('https://api.gu1.ai/api/kyc/face-match', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer SUA_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    documentImage: 'data:image/jpeg;base64,/9j/4AAQ...',
    selfieImage: 'data:image/jpeg;base64,/9j/4AAQ...',
    entityId: '123e4567-e89b-12d3-a456-426614174000',
  }),
});

const result = await response.json();
console.log('Match:', result.match, 'Score:', result.score);

​
Respostas de erro

As respostas usam mensagens genéricas (sem nomes de provedores). Códigos comuns:
CódigoHTTPSignificado
NOT_CONFIGURED403Credenciais do Face Match não configuradas na organização.
NOT_ENABLED403A integração Face Match não está ativada para esta organização.
INVALID_REQUEST400Imagens inválidas ou ausentes (formato/tamanho).
UNAUTHORIZED401Credenciais de API/verificação inválidas ou ausentes.
QUOTA_EXCEEDED403Não foi possível completar a verificação (cota/créditos).
SERVICE_UNAVAILABLE503Serviço de verificação temporariamente indisponível.
VERIFICATION_FAILED500Falha genérica; tentar novamente ou usar outras imagens.

​
Auditoria e listagem de verificações

Cada solicitação de Face Match (sucesso ou falha) é armazenada em face_match_verifications para auditoria e conformidade. A resposta inclui verificationId (ID do registro de auditoria). Cada registro armazenado também guarda o limiar usado naquele momento (para exibir no histórico mesmo que o limiar da organização mude depois).

​
Listar registros de auditoria

GET https://api.gu1.ai/api/kyc/face-match/verifications?entityId={entityId}&limit=50&offset=0
Parâmetros de query:
ParâmetroTipoDescrição
entityIdstring (UUID)Opcional. Filtrar por entidade pessoa.
statusstringOpcional. Filtrar por status (approved, declined, in_review, failed).
limitnumberQuantidade máxima (padrão 50, máx. 100).
offsetnumberDeslocamento para paginação.
Resposta: { "verifications": [ ... ], "scoreDeclineThreshold": 30, "pagination": { "limit", "offset", "total" } }. Cada verificação inclui id, entityId, status, match, score, threshold (valor usado naquela execução), createdAt e opcionalmente caminhos de imagens para auditoria.

​
Obter verificação por ID

Recuperar um único registro de auditoria de Face Match pelo seu verificationId (retornado na resposta do POST ou na listagem). 
GET https://api.gu1.ai/api/kyc/face-match/verifications/:id
Parâmetro de path: id — UUID da verificação (o mesmo que verificationId do POST ou da listagem). Resposta (200): Um objeto de verificação com os mesmos campos de cada item da listagem: id, organizationId, entityId, status, match, score, requestId, vendorData, errorMessage, triggeredByUserId, createdAt, documentStoragePath, selfieStoragePath, storageProvider, threshold. Erros: 404 NOT_FOUND se o ID não existir ou pertencer a outra organização; 401 UNAUTHORIZED se não autenticado.

​
Convivência com KYC por sessão

  • Fluxo por sessão cria um registro em kyc_validations, envia o usuário a uma URL hospedada e atualiza o status via webhooks. A decisão armazenada inclui documento, liveness e comparação facial da sessão ao vivo.
  • Face Match cria um registro de auditoria em face_match_verifications e retorna o resultado na mesma resposta. Não cria um registro em kyc_validations. Use quando precisar de uma verificação pontual (por exemplo “essas duas imagens são da mesma pessoa?”) sem sessão hospedada.
  • Ambos usam a mesma configuração KYC da organização. O limiar do Face Match é configurado em Configurações da organização → KYC (card Face Match).

​
Próximos passos

Criar Validação KYC

Verificação por sessão com URL hospedada

Listar Validações

Listar validações KYC por entidade