Buscar face

Serviço que busca um rosto em uma coleção facial e retorna a melhor correspondência com sua confiança.

Endpoint

POST /biometric/face/collections/{collectionId}/search

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.

Parâmetros de rota

Parâmetro	Tipo	Obrigatório	Descrição
collectionId	string	Sim	Identificador da coleção.

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.
face	string	Sim	Rosto a ser buscado: chave do asset TOKEN_BEST_IMAGE ou seu conteúdo em Base64.

Exemplo de solicitação

{
  "source": "FILE_KEY",
  "face": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_BEST_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.
collectionId	string	Coleção consultada.
faceId	string	Rosto correspondente, se houver.
confidence	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:08.000Z",
  "message": "Service executed ok",
  "collectionId": "clientes-web",
  "faceId": "face-0091",
  "confidence": 0.9731
}

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 SEARCH_FACE.
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.