> 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/authenticate-facial.md).

# Autenticação facial

Serviço que realiza a validação facial entre dois rostos, incluindo tanto **imagens abertas** quanto **templates biométricos**.

Este serviço pode ser usado para realizar as seguintes validações:

1. Autenticação facial entre duas **imagens abertas**, geradas ou não por Widgets da FacePhi.
2. Autenticação facial entre dois **templates biométricos**, requer a integração do Widget Selphi Mobile ou Web da FacePhi.
3. Autenticação facial entre uma **imagem aberta** e um **template biométrico**, requer a integração do Widget Selphi Mobile ou Web da FacePhi.
4. Autenticação facial entre o rosto presente na **foto do Documento de identidade (TokenFaceImage)** e uma **imagem aberta**, requer a integração do Widget SelphID Mobile da FacePhi.
5. Autenticação facial entre o rosto presente na **foto do Documento de identidade (TokenFaceImage)** e um **template biométrico**, requer a integração dos Widgets Selphi Mobile e SelphID Mobile da FacePhi.

### Integração

* Para as **validações do tipo 4 e 5**, é necessário implementar o Widget SelphID Mobile para gerar a propriedade **TokenFaceImage**.
* Para as **validações do tipo 2, 3 e 5**, é necessário implementar o Widget Selphi Mobile ou Web para gerar a **propriedade do template biométrico (TemplateRaw)**.

### Endpoint

```
POST /services/authenticateFacial
```

### 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                                                                                                                                                                                                                     |
| ---------------------- | ------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token1`               | string  | **Sim**     | Imagem usada como **referência** para a comparação facial. Dependendo do método invocado, pode ser o token gerado pelos Widgets SelphID (token da foto do documento), uma imagem aberta ou um template biométrico tokenizado. |
| `token2`               | string  | **Sim**     | Imagem usada para a **comparação**. Pode ser uma imagem aberta ou um template biométrico tokenizado.                                                                                                                          |
| `method`               | inteiro | **Sim**     | Indica o **método de comparação** invocado. Consulte [Especificação de método](#especificación-de-método).                                                                                                                    |
| `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.                                                                                                                                                                         |

#### Especificação de método

| Método | Descrição                                                                                                   | Entrada                                     |
| ------ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| **1**  | Autenticação facial por meio de **imagens abertas**                                                         | token1: Base64, token2: Base64              |
| **2**  | Autenticação facial por meio de **Templates Biométricos**                                                   | token1: templateRaw, token2: templateRaw    |
| **3**  | Autenticação facial por meio de uma **imagem aberta** e um **Template Biométrico**                          | token1: Base64, token2: templateRaw         |
| **4**  | Autenticação facial por meio do **token gerado pelo recorte da foto do documento** e uma imagem aberta      | token1: tokenFaceImage, token2: Base64      |
| **5**  | Autenticação facial por meio do **token gerado pelo recorte da foto do documento** e um Template Biométrico | token1: tokenFaceImage, token2: templateRaw |

#### Exemplo de solicitação

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

{% hint style="warning" %}
**Tamanho máximo da solicitação: 6 MB.** Todas as imagens em Base64 da solicitação são contabilizadas em conjunto para esse limite, com uma sobrecarga de \~33% em relação ao arquivo original (máximo de \~4,5 MB de arquivos originais no total). Recomendamos imagens JPEG comprimidas de no máximo 1–2 MB cada. 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 ocorre um erro ou uma exceção no módulo.                               |
| `serviceTime`                       | string  | Tempo total de processamento **(milissegundos)**.                                                                                                   |
| `serviceTransactionId`              | string  | Identificador da transação associado à solicitação processada pela API.                                                                             |
| `serviceFacialAuthenticationHash`   | string  | Hash de integridade do Template Biométrico usado em uma autenticação facial positiva ou incerta. **Aplicável somente aos métodos 2, 3 e 5.**        |
| `serviceFacialAuthenticationResult` | inteiro | Código que indica o **resultado da correspondência facial**. Consulte [Service Facial Authentication Result](#service-facial-authentication-result) |
| `serviceFacialSimilarityResult`     | número  | Valor que indica a **similaridade facial** entre o rosto na foto do Documento de identidade e a selfie tirada pelo usuário. **1.0 = 100%**          |

#### 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 da autenticação facial do serviço

O `serviceFacialAuthenticationResult` indica o resultado das operações de correspondência facial:

| Código | Resultado                        | Descrição                                                                                                                                                                                                  |
| ------ | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0      | NONE                             | Não foi possível realizar a verificação facial.                                                                                                                                                            |
| 1      | NEGATIVE                         | O processo foi executado corretamente. A comparação dos padrões faciais dos rostos não corresponde.                                                                                                        |
| 3      | POSITIVE                         | O processo foi executado corretamente. A comparação dos padrões faciais dos rostos é positiva. O valor de `serviceFacialSimilarityResult` indica o percentual de similaridade entre as imagens comparadas. |
| 4      | NONE BECAUSE POSE EXCEED         | Não foi possível realizar a verificação facial devido à posição do rosto.                                                                                                                                  |
| 5      | NONE BECAUSE INVALID EXTRACTIONS | Não foi possível realizar a verificação facial devido a problemas na extração do padrão facial.                                                                                                            |

#### Exemplo de resposta: Positive

```json
{
  "serviceResultCode": 0,
  "serviceResultLog": "Positive",
  "serviceTime": "516",
  "serviceTransactionId": "a29cbe15-2b68-495f-b7eb-be985b21c486",
  "serviceFacialAuthenticationHash": "47D0ACDCF08C348469C2F512BB59216B46DCD9B253822ED0E4EEAFCEB76AADD5AEF20CA31EC52D03EB290EBC91A6AD65FB0416F9EB2164D3854932153074289E",
  "serviceFacialAuthenticationResult": 3,
  "serviceFacialSimilarityResult": 0.99153554
}
```

#### Exemplo de resposta: Negative

```json
{
  "serviceResultCode": 0,
  "serviceResultLog": "Negative",
  "serviceTime": "502",
  "serviceTransactionId": "e96e85a4-3f94-4000-b639-15c4f18c345b",
  "serviceFacialAuthenticationHash": "09B9A4097E3642ADEDB665BA2E15B096FFB65A039E0D7137D0AD38666F90A010624C26867E6A7DB8346385610CC9FEDE435C3CC6A2AC9B008DD98C6EFE8C42E7",
  "serviceFacialAuthenticationResult": 1,
  "serviceFacialSimilarityResult": 0.01190000
}
```

#### `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"
}
```
