Face Match for Liveness

O {livenessRequestId} deste endpoint é o id devolvido pela chamada anterior ao Liveness. A imagem que você envia aqui é comparada com a face capturada naquela sessão, e a resposta diz apenas se as duas são da mesma pessoa.

É a segunda metade do fluxo de liveness: primeiro se prova que há uma pessoa viva na captura, depois se prova que aquela pessoa é a mesma de outra imagem — a foto de um documento, por exemplo.

🚧 A sessão de liveness precisa ter sido aprovada

A comparação só é executada quando a sessão de liveness referenciada resultou em isAlive: true. Se a sessão não existir ou tiver sido reprovada, a resposta vem com matched: false e código 200, sem que nenhuma comparação aconteça.

Request

POST /face-match-for-liveness/{livenessRequestId}/v2

Parâmetros

Parâmetro	Descrição	Obrigatório
livenessRequestId	O id devolvido pela chamada ao Liveness que capturou a face de referência.	Sim

Headers

Authorization: ApiKey <sua-chave-de-api>

Este endpoint também aceita o token JWT, no formato Authorization: Bearer <accessToken>. Veja Token JWT.

Arquivos aceitos

Item	Valor
Formatos	image/png, image/jpeg
Quantidade por chamada	1 arquivo
Tamanho máximo (multipart)	15 MB

O nome do campo do formulário é livre. Se mais de um arquivo for enviado, a requisição é recusada com 422.

Além do multipart/form-data, o arquivo pode ser enviado em JSON, no campo base64, como descrito em Envio de arquivos.

Exemplo Request

curl -i -X POST 'https://api-homolog.nxcd.app/face-match-for-liveness/13cfec7c-b238-4820-a4d1-5173e4c1418e/v2' \
  --header 'Authorization: ApiKey SUA_CHAVE_AQUI' \
  --form 'documento=@./documento-frente.jpg'

Response

TIP

A resposta deste endpoint não usa o envelope id / version / data / metadata dos demais endpoints de análise. O corpo tem um único campo. O identificador da requisição continua disponível no header Nextid-ReqId.

Campo	Descrição	Tipo
matched	true quando a face da imagem enviada é a mesma da sessão de liveness referenciada.	Boolean

Exemplos JSON

1. As faces correspondem

Status Code: 200

{
  "matched": true
}

2. As faces não correspondem, ou a comparação não pôde ser feita

Status Code: 200

{
  "matched": false
}

🚧 matched: false tem mais de um significado

A mesma resposta cobre "as faces são de pessoas diferentes" e "não havia o que comparar". Os casos que devolvem matched: false sem executar a comparação são:

• nenhum arquivo foi enviado na requisição;
• o livenessRequestId não corresponde a nenhuma sessão de liveness;
• a sessão de liveness foi reprovada (isAlive: false);
• não há registro do arquivo da sessão de liveness, nem no cache da requisição nem na tarifação.

Para distinguir esses casos, verifique o resultado do liveness antes de chamar este endpoint e guarde o id da sessão.

Headers de resposta

Header	Quando aparece
Nextid-ReqId	Em todas as respostas. Traz o identificador desta requisição.

Erros

Código	Quando ocorre
401 Unauthorized	Chave de API ou token JWT ausente, inválido, ou sem permissão para o liveness.
404 Not Found	A versão informada na URL não existe, ou o arquivo da sessão de liveness está registrado, mas não foi encontrado no armazenamento.
406 Not Acceptable	O corpo foi enviado como JSON, mas sem o campo base64.
413 Payload Too Large	O arquivo enviado em multipart/form-data passa de 15 MB.
415 Unsupported Media Type	O header Content-Type está ausente ou não é suportado.
422 Unprocessable Entity	O formato do arquivo não é aceito, ou foi enviado mais de um arquivo na mesma chamada.
500 Internal Server Error	Falha inesperada durante o processamento.

TIP

Um livenessRequestId inexistente não gera 404: a resposta é 200 com matched: false. São situações distintas: quando não há o que comparar, a resposta é 200 com matched: false; o 404 só ocorre quando a sessão existe e tem um arquivo registrado, mas esse arquivo não está mais no armazenamento.

O formato das respostas de erro está descrito em Códigos HTTP das respostas.

Versões

Este endpoint aceita a versão v2 no fim da URL. Omitindo a versão, a chamada é atendida pela v2.

Versão	Situação	O que muda
v2	Recomendada	É a versão usada quando nada é informado na URL.

O único campo devolvido é o matched. Omitir a versão dá no mesmo: /face-match-for-liveness/{livenessRequestId} e /face-match-for-liveness/{livenessRequestId}/v2 são a mesma chamada. Prefira informar a v2 no caminho.

Um valor não reconhecido na posição da versão devolve 404.

🚧 Não confunda com o Face Match

O /face-match, documentado à parte, compara faces entre os arquivos que você envia na mesma requisição e devolve o envelope completo. Este endpoint aqui compara com a face de uma sessão de liveness anterior e devolve só o matched.