> 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/identity-api/identity-api-reference/shared-biometric-components/evaluate-passive-liveness-token.md).

# Avaliar Token de Liveness passivo

Este serviço realiza uma verificação de vivacidade usando a **melhor imagem tokenizada** obtida durante a captura da selfie do usuário. Para gerar a imagem tokenizada, é usada a **função nativa do widget Selphi**, com o **parâmetro bestImage** (imagem aberta) gerado pelo widget.

### Integração

Requer a implementação do **widget Selphi Mobile** ou do **widget Selphi Web**.

### Endpoint

```
POST /services/evaluatePassiveLivenessToken
```

### Cabeçalhos

| Nome          | Tipo   | Obrigatório | Descrição                                                     |
| ------------- | ------ | ----------- | ------------------------------------------------------------- |
| **x-api-key** | string | **Sim**     | API Key de autorização de acesso.                             |
| **family**    | string | Não         | Valor: **OnBoarding**. Obrigatório com o serviço de tracking. |

{% hint style="info" %}
Todas as chamadas aos endpoints de tracking com **Identity Platform** devem conter o cabeçalho `family`.
{% endhint %}

### Corpo da solicitação

**Content-Type:** `application/json`

#### Parâmetros

| Parâmetro              | Tipo   | Obrigatório | Descrição                                                                                                 |
| ---------------------- | ------ | ----------- | --------------------------------------------------------------------------------------------------------- |
| `imageBuffer`          | string | **Sim**     | Propriedade **BestImage** gerada pelo widget Selphi e **tokenizada** por meio da função nativa do widget. |
| `tracking`             | object | Não         | Objeto que representa as informações de acompanhamento necessárias.                                       |
| `tracking.extraData`   | string | Não         | Token gerado pelo SDK Mobile/Web. Contém informações de acompanhamento tokenizadas com a Plataforma.      |
| `tracking.operationId` | string | Não         | Identificador da operação gerado pelo SDK Mobile/Web.                                                     |

#### Exemplo de solicitação

```json
{
  "imageBuffer": "BAMBAQLNHJoWGPjfeuDIzDXdZuP...",
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN4kLmPqYf7R...",
    "operationId": "123e4567-e89b-12d3-a456-426614174000"
  }
}
```

{% hint style="warning" %}
**Tamanho máximo da solicitação: 6 MB.** A imagem em Base64 (`imageBuffer`) e os demais campos contam para esse limite, com um acréscimo de \~33% em relação ao arquivo original (máximo de \~4,5 MB para o arquivo original). Recomendamos imagens JPEG comprimidas de, no máximo, 1–2 MB. Se o limite for excedido, o gateway responde `413` sem processar a solicitação. Consulte [Limite de tamanho da solicitação](https://docs.facephi.com/pages/1b12810f7c9abac00ee2fed384b12d3575d93434#l%C3%ADmite-de-tama%C3%B1o-de-la-solicitud).
{% endhint %}

### Respostas

#### `200` Sucesso

#### Parâmetros de resposta

| Parâmetro               | Tipo    | Descrição                                                                                                                         |
| ----------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `serviceResultCode`     | inteiro | Código que indica o **resultado geral** da execução do serviço. Consulte [Service Result Code](#service-result-code)              |
| `serviceResultLog`      | string  | Campo descritivo do resultado da execução do serviço. Inclui detalhes quando há um erro ou uma exceção.                           |
| `serviceTime`           | string  | Tempo total de resposta **(milissegundos)**.                                                                                      |
| `serviceTransactionId`  | string  | Identificador da transação associado à solicitação processada pela API.                                                           |
| `serviceLivenessResult` | inteiro | Código que indica o **resultado do teste de vida passivo**. Consulte [Resultado do serviço de Liveness](#service-liveness-result) |

#### Código de resultado do serviço

O `serviceResultCode` indica o resultado geral da execução do serviço:

| serviceResultCode | Descrição                                                                              | Código HTTP |
| ----------------- | -------------------------------------------------------------------------------------- | ----------- |
| 0                 | A execução do serviço foi bem-sucedida; o módulo processou a solicitação corretamente. | 200         |

#### Resultado de Liveness do serviço

O `serviceLivenessResult` indica o resultado da avaliação do teste de vida passivo:

| Código | Resultado                       | Descrição                                                                                             |
| ------ | ------------------------------- | ----------------------------------------------------------------------------------------------------- |
| 0      | None                            | Não foi possível avaliar o teste de vida.                                                             |
| 1      | Spoof                           | OBSOLETO. Use 'NoLive' no lugar.                                                                      |
| 2      | Uncertain                       | OBSOLETO                                                                                              |
| 3      | Live                            | Presume-se que o sujeito esteja vivo.                                                                 |
| 4      | NoneBecauseBadQuality           | Não foi possível avaliar o teste de vida devido à baixa qualidade da imagem.                          |
| 5      | NoneBecauseFaceTooClose         | Não foi possível avaliar o teste de vida porque os rostos detectados estão muito próximos das bordas. |
| 6      | NoneBecauseFaceNotFound         | Não foi possível avaliar o teste de vida porque nenhum rosto foi detectado.                           |
| 7      | NoneBecauseFaceTooSmall         | Não foi possível avaliar o teste de vida porque os rostos detectados são muito pequenos.              |
| 8      | NoneBecauseAngleTooLarge        | Não foi possível avaliar o teste de vida porque o ângulo entre os rostos excede o limite permitido.   |
| 9      | NoneBecauseImageDataError       | Não foi possível avaliar o teste de vida devido a erros no formato da imagem.                         |
| 10     | NoneBecauseInternalError        | Não foi possível avaliar o teste de vida devido a um erro interno.                                    |
| 11     | NoneBecauseImagePreprocessError | Não foi possível avaliar o teste de vida devido a um erro no pré-processamento da imagem.             |
| 12     | NoneBecauseTooManyFaces         | Não foi possível avaliar o teste de vida porque muitos rostos foram detectados na imagem.             |
| 13     | NoneBecauseFaceTooCloseToBorder | Não foi possível avaliar o teste de vida porque o rosto está muito próximo da borda.                  |
| 14     | NoneBecauseFaceCropped          | Não foi possível avaliar o teste de vida porque o rosto está cortado.                                 |
| 15     | NoneBecauseLicenseError         | Não foi possível avaliar o teste de vida devido a um erro de licença.                                 |
| 16     | NoneBecauseFaceOccluded         | Não foi possível avaliar o teste de vida porque o rosto está obstruído.                               |
| 17     | NoLive                          | Não foi detectada vida.                                                                               |
| 18     | NoneBecauseEyesClosed           | Não foi possível avaliar o teste de vida porque os olhos da pessoa estão fechados.                    |

#### Exemplo de resposta: Live

```json
{
  "serviceResultCode": 0,
  "serviceResultLog": "Live",
  "serviceTime": "799",
  "serviceTransactionId": "35d93da8-b843-4033-8e78-c0aabedcef8b",
  "serviceLivenessResult": 3
}
```

#### Exemplo de resposta: NoLive

```json
{
  "serviceResultCode": 0,
  "serviceResultLog": "NoLive",
  "serviceTime": "81",
  "serviceTransactionId": "3f332c81-3dfa-4952-b593-20e3b5651b5b",
  "serviceLivenessResult": 0
}
```

#### `400` Solicitação inválida

```json
{
  "status": 400,
  "title": "Solicitação inválida",
  "detail": "Solicitação inválida.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}
```

#### `401` Não autorizado

```json
{
  "message": "Unauthorized"
}
```

#### `403` Proibido

```json
{
  "Message": "User is not authorized to access this resource with an explicit deny"
}
```

#### `413` Payload muito grande

A solicitação excede o tamanho máximo permitido. O gateway a rejeita **sem processá-la**: a resposta não inclui `serviceResultCode` nem `serviceTransactionId`. Consulte [Limite de tamanho da solicitação](https://docs.facephi.com/pages/1b12810f7c9abac00ee2fed384b12d3575d93434#l%C3%ADmite-de-tama%C3%B1o-de-la-solicitud).

Solicitação maior que 6 MB e de até 10 MB (`Content-Type: application/json`):

```json
{
  "message": "Request Too Long"
}
```

Solicitação maior que 10 MB (10.485.760 bytes) (`Content-Type: text; charset=utf-8`, texto simples, não JSON):

```
HTTP content length exceeded 10485760 bytes.
```

#### `502` Bad Gateway

```json
{
  "status": 502,
  "title": "Bad Gateway",
  "detail": "Server got an invalid response.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502"
}
```

#### `504` Timeout do gateway

```json
{
  "message": "Endpoint request timed out"
}
```
