> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-pt-br/api-rest/midapi-v2/face-collections/search-face.md).

# Pesquisar 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](/docs.facephi-pt-br/api-rest/midapi-v2/autenticacion.md).                                                           |
| **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](/docs.facephi-pt-br/api-rest/midapi-v2/storage.md). |

### 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](/docs.facephi-pt-br/api-rest/midapi-v2/storage.md). |
| `face`    | string | **Sim**     | Rosto a ser buscado: chave do asset `TOKEN_BEST_IMAGE` ou seu conteúdo em Base64.                                                                                                         |

#### Exemplo de solicitação

```json
{
  "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

```json
{
  "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](/docs.facephi-pt-br/api-rest/midapi-v2.md#respuestas-de-error).