Skip to main content
POST
/
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": {},
  "selfieImage": {},
  "entityId": "<string>",
  "scoreThreshold": 123,
  "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 (como arquivos ou 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

​
Content-Type

Apenas multipart/form-data é aceito. Você pode enviar as imagens de duas formas (ou misturar):
  1. Como arquivos: anexar arquivos de imagem nos campos do form documentImage e selfieImage.
  2. Como strings base64: enviar os mesmos nomes de campo com a imagem em base64 (com ou sem prefixo data:image/...;base64,).
Se uma imagem obrigatória estiver faltando (nem arquivo nem base64 para esse campo), a API retorna 400. Para cada imagem, se você enviar arquivo e base64, o arquivo tem prioridade.

​
Headers

Authorization: Bearer SUA_API_KEY
Content-Type: multipart/form-data; boundary=----...
Não defina Content-Type manualmente ao usar FormData; o cliente define com o boundary correto. Se sua conta usa escopo por organização, inclua: 
X-Organization-Id: SEU_ORGANIZATION_ID

​
Campos do form

​
documentImage
file | string
required
Imagem de referência (por exemplo a foto do documento). Enviar como arquivo (recomendado) ou como string (base64, com ou sem prefixo data:image/...;base64,). Formatos: JPEG, PNG, WebP, TIFF. Máx. 5MB.
​
selfieImage
file | string
required
Imagem da selfie. Mesmo que documentImage: arquivo ou base64. Obrigatório.
​
entityId
string
UUID opcional da entidade pessoa a associar a esta verificação. Usado para auditoria e para listar verificações por entidade.
​
scoreThreshold
number
Opcional. Limiar 0–100; resultados abaixo são recusados. Se omitido, usa o limiar configurado na organização (ou 30 por padrão).
​
vendorData
string
Referência opcional (por exemplo seu ID de usuário) para rastreamento. Armazenada no registro de auditoria.

​
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.
scoreDeclineThresholdnumberLimiar (0–100) usado nesta verificação (configuração da org).
requestIdstring (opcional)ID interno da solicitação (suporte).
warningsstring[] (opcional)Array de códigos de risco (ex.: LOW_FACE_MATCH_SIMILARITY, NO_REFERENCE_IMAGE). Veja Códigos de risco em avisos.

​
Exemplo de solicitação

const form = new FormData();
form.append('documentImage', documentFile);
form.append('selfieImage', selfieFile);
form.append('entityId', '123e4567-e89b-12d3-a456-426614174000');

const response = await fetch('https://api.gu1.ai/api/kyc/face-match', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer SUA_API_KEY' },
  body: form,
});
const result = await response.json();

​
Erros

CódigoHTTPSignificado
NOT_CONFIGURED403Credenciais Face Match não configuradas na organização.
NOT_ENABLED403Integração Face Match não ativada.
INVALID_REQUEST400Content-Type não é multipart/form-data ou imagens faltando/inválidas (sem arquivo nem base64 para campo obrigatório).
UNAUTHORIZED401Credenciais inválidas ou faltando.
VERIFICATION_FAILED500Falha genérica; tentar novamente ou outras imagens.

​
Auditoria e listagem

Cada solicitação é armazenada em face_match_verifications. Para listar: 
GET https://api.gu1.ai/api/kyc/face-match/verifications?entityId={entityId}&limit=50&offset=0
Para obter uma verificação por ID: 
GET https://api.gu1.ai/api/kyc/face-match/verifications/:id

​
Próximos passos

Criar validação KYC

Verificação por sessão com URL hospedada

Face Match (Documento + Selfie)

Comparar documento e selfie