Face Match (Documento + Selfie)

Resumo

Face Match é um serviço de verificação da Gu1 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:

Integração Face Match ativada: Sua organização deve ter a integração KYC Face Match ativada (por exemplo no Marketplace / Integrações).
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 Gu1).
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 Gu1. Toda a verificação é feita na infraestrutura da Gu1.

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

Como arquivos: anexar arquivos de imagem nos campos do form documentImage e selfieImage.
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.

doubleCheckRenaper

boolean

Com true, após aprovação do face match Gu1 executa RENAPER biométrico (validate-dni com selfie) e dados (renaper/data: DNI + trâmite). Requer credenciais RENAPER da org e integrações Marketplace ativas: ar_renaper_data_enrichment e ar_renaper_validate_dni_enrichment. Query prevalece sobre o body.

doubleCheckRenaper

boolean

Igual ao query param doubleCheckRenaper.

documentNumber

string

DNI para RENAPER quando doubleCheckRenaper=true. Opcional se entityId resolver taxId ou person.idNumber.

gender

string

Gênero para RENAPER (M, F, male, female). Obrigatório salvo resolução pela entidade vinculada.

personalNumber

string

required

Número de trâmite para chequeo RENAPER. Obrigatório com doubleCheckRenaper=true.

O limiar mínimo (threshold) pode ser enviado no form; se não for enviado, é lido da configuração KYC da organização. A resposta inclui o limiar usado na chamada.

Resposta

Resposta de sucesso (200 OK)

Campo	Tipo	Descrição
`match`	boolean	Se as faces foram consideradas coincidentes (pontuação ≥ limiar).
`score`	number	Pontuação de similaridade 0–100.
`status`	string	`"approved"` \| `"declined"` \| `"in_review"`.
`verificationId`	string	ID do registro de auditoria em `face_match_verifications` (suporte e listagem).
`scoreDeclineThreshold`	number	Limiar (0–100) usado nesta verificação (configuração da org).
`requestId`	string (opcional)	ID interno da solicitação (suporte).
`warnings`	string[] (opcional)	Array de códigos de risco da verificação (ex.: `LOW_FACE_MATCH_SIMILARITY`, `NO_REFERENCE_IMAGE`). Veja Códigos de risco em avisos para todos os valores.
`doubleCheckRenaper`	boolean (opcional)	`true` se dupla verificação RENAPER foi solicitada.
`responseDoubleChecks`	object (opcional)	Com `doubleCheckRenaper=true`: `renaper` (dados/trâmite) e `renaperBiometric` (ABIS). Mesma forma que KYC validations RENAPER.

Se RENAPER falhar após aprovação do provedor, match vira false, status vira "declined" e códigos RENAPER entram em warnings. Use timeout HTTP ≥ 60 s com double-check. 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 form = new FormData();
form.append('documentImage', documentFile); // File object
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();
console.log('Match:', result.match, 'Score:', result.score);

Respostas de erro

Códigos de erro comuns:

Código	HTTP	Significado
`NOT_CONFIGURED`	403	Credenciais Face Match não configuradas na organização.
`NOT_ENABLED`	403	Integração Face Match não ativada para esta organização.
`INVALID_REQUEST`	400	Content-Type não é multipart/form-data, ou imagens faltando/inválidas (ex.: sem arquivo nem base64 para campo obrigatório, formato/tamanho).
`UNAUTHORIZED`	401	Credenciais de API/verificação inválidas ou faltando.
`QUOTA_EXCEEDED`	403	Não foi possível concluir a verificação (ex.: cota/créditos).
`SERVICE_UNAVAILABLE`	503	Serviço de verificação temporariamente indisponível.
`VERIFICATION_FAILED`	500	Não foi possível concluir a verificação; tentar novamente ou 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 salvo também armazena o limiar usado no momento da chamada (para exibir no histórico mesmo que o limiar da org 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âmetro	Tipo	Descrição
`entityId`	string (UUID)	Opcional. Filtrar por entidade pessoa.
`status`	string	Opcional. Filtrar por status (`approved`, `declined`, `in_review`, `failed`).
`limit`	number	Máximo de itens (padrão 50, máx. 100).
`offset`	number	Deslocamento da 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 caminhos de imagem opcionais para auditoria.

Obter verificação por ID

Obtém um registro de auditoria de Face Match pelo 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 (igual ao 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 estiver 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 face match da sessão ao vivo.
Face Match cria um registro de auditoria em face_match_verifications e retorna o resultado na mesma solicitação. Não cria registro em kyc_validations. Use quando precisar de uma verificação pontual (ex.: «estas duas imagens são a mesma pessoa?») sem sessão hospedada.
Ambos usam a mesma configuração KYC da organização. O limiar do Face Match é definido em Configurações da organização → KYC (card Face Match).

Face Match (Documento + Selfie)

Resumo

Pré-requisitos

Solicitação

Endpoint

Content-Type

Headers

Campos do form

Resposta

Resposta de sucesso (200 OK)

Exemplo de solicitação

Respostas de erro

Auditoria e listagem de verificações

Listar registros de auditoria

Obter verificação por ID

Convivência com KYC por sessão

Próximos passos

Criar validação KYC

Listar validações

Documentation Index

​Resumo

​Pré-requisitos

​Solicitação

​Endpoint

​Content-Type

​Headers

​Campos do form

​Resposta

​Resposta de sucesso (200 OK)

​Exemplo de solicitação

​Respostas de erro

​Auditoria e listagem de verificações

​Listar registros de auditoria

​Obter verificação por ID

​Convivência com KYC por sessão

​Próximos passos

Criar validação KYC

Listar validações

Resumo

Pré-requisitos

Solicitação

Endpoint

Content-Type

Headers

Campos do form

Resposta

Resposta de sucesso (200 OK)

Exemplo de solicitação

Respostas de erro

Auditoria e listagem de verificações

Listar registros de auditoria

Obter verificação por ID

Convivência com KYC por sessão

Próximos passos