> 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/biometric-services/face-liveness.md).

# Face Liveness

Serviço que determina se a selfie corresponde a uma pessoa presente no momento da captura.

### Endpoint

```
POST /biometric/face/liveness
```

### 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). |

### 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). |
| `image`   | string | **Sim**     | Selfie: chave do asset `TOKEN_BEST_IMAGE` ou seu conteúdo em Base64.                                                                                                                      |

#### Exemplo de solicitação

```json
{
  "source": "FILE_KEY",
  "image": "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.       |
| `livenessResult` | string | Resultado do teste de vida: `LIVE`, `NO_LIVE` ou `ERROR`.   |

#### Exemplo de resposta

```json
{
  "consumerId": "consumer-web",
  "transactionId": "a29cbe15-2b68-495f-b7eb-be985b21c486",
  "timestamp": "2026-06-26T12:00:05.000Z",
  "message": "Service executed ok",
  "livenessResult": "LIVE"
}
```

#### 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 `LIVENESS`.                                                                                                                                                                                                                                                                          |
| `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).