Matching Facial

Serviço que compara dois rostos e devolve o resultado da correspondência com sua confiança.

A ordem dos espaços reservados é significativa: sourceImage é a selfie e targetImage o rosto do documento.

Endpoint

POST /biometric/face/matching

Cabeçalhos

Nome	Tipo	Obrigatório	Descrição
Authorization	string	Sim	Token de consumer no formato Bearer <token>. Ver Autenticação.
consumer-id	string	Sim	Identificador do consumer.
operation-id	string	Condicional	Identificador da operação à qual pertencem os assets referenciados. Obrigatório quando source é FILE_KEY. Ver Armazenamento.

Corpo da solicitação

Content-Type: application/json

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
source	string	Sim	Modo como os assets são fornecidos: FILE_KEY para chaves de assets armazenados, FILE para conteúdo em Base64. Ver Armazenamento.
sourceImage	string	Sim	Selfie a ser comparada: chave do asset TOKEN_BEST_IMAGE ou seu conteúdo em Base64.
targetImage	string	Sim	Rosto com o qual se compara: rosto recortado do documento (TOKEN_FACE_IMAGE) ou Token de seu anverso (TOKEN_FRONT_DOCUMENT), ou seu conteúdo em Base64.

Exemplo de solicitação

{
  "source": "FILE_KEY",
  "sourceImage": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_BEST_IMAGE",
  "targetImage": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_FACE_IMAGE"
}

Respostas

200 Sucesso

Parâmetros de resposta

Parâmetro	Tipo	Descrição
consumerId	string	Identificador do consumer que realizou a chamada.
transactionId	string	Identificador da transação.
timestamp	string	Carimbo de data e hora da resposta no formato ISO 8601.
message	string	Campo descritivo do resultado da execução do serviço.
facialMatchingResult	string	Resultado da correspondência facial: POSITIVE, NEGATIVE ou ERROR.
facialMatchingConfidence	number	Confiança da correspondência. 1.0 = 100%

Exemplo de resposta

{
  "consumerId": "consumer-web",
  "transactionId": "e96e85a4-3f94-4000-b639-15c4f18c345b",
  "timestamp": "2026-06-26T12:00:06.000Z",
  "message": "Service executed ok",
  "facialMatchingResult": "POSITIVE",
  "facialMatchingConfidence": 0.99153554
}

Outras respostas

Código	Descrição
400	Campo obrigatório ausente ou valor não admitido; falta o cabeçalho operation-id havendo referências; ou uma chave não tem a forma {operationId}/{CONTEXTO} ou declara um contexto que o espaço reservado não admite.
403	O consumer não está provisionado com o serviço FACIAL_MATCHING.
404	A operação declarada em operation-id não existe ou pertence a outro consumer.
409	Um asset referenciado contém um conteúdo já processado em outra operação.
410	A operação declarada em operation-id expirou.
422	Uma chave nomeia uma operação diferente da declarada em operation-id, ou o contexto não tem nenhum asset armazenado.
429	O consumer excedeu seu limite de taxa de requisições, ou um asset referenciado esgotou seu orçamento de invocações neste Endpoint. No primeiro caso a resposta inclui Retry-After, X-RateLimit-Limit e X-RateLimit-Burst, e esperar resolve; no segundo, não. O serviço subjacente não é invocado e a chamada não é faturada.

O corpo de uma resposta de erro tem o formato descrito em MIDAPI v2.