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

# Autenticar usuário

Este serviço valida tanto a prova de vida quanto a autenticação facial. Compara o Template Biométrico, previamente validado e armazenado no repositório de dados do cliente durante o processo de Onboarding, com um bestImageToken gerado no momento da autenticação.

#### Funcionalidade

* **Primeira chamada**: Define um userId único para o usuário.
* **Autenticação**: Em cada tentativa de autenticação, o userId é enviado junto com o Template Biométrico registrado. Esse template é comparado com a imagem tokenizada atual (bestImageToken). Se houver correspondência e a verificação de vida for aprovada, o usuário é autenticado com sucesso.

### Integração

Requer a implementação do **Widget Selphi Mobile** ou do **Widget Selphi Web** para gerar o **bestImageToken** e a **Template Biométrico (TemplateRaw)**.

### Endpoint

```
POST /services/authenticateUser
```

### 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: **Authentication**. Obrigatório com o serviço de tracking. |

{% hint style="info" %}
Todas as chamadas aos Endpoints para tracking com **Identity Platform** devem conter o header `family`.
{% endhint %}

### Corpo da solicitação

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

#### Parâmetros

| Parâmetro               | Tipo   | Obrigatório | Descrição                                                                                                                                                                |
| ----------------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `userId`                | string | **Sim**     | Identificador único do usuário. Deve ser persistido e associado ao Template Biométrico correspondente. Precisa de pelo menos dois dígitos.                               |
| `registeredTemplateRaw` | string | **Sim**     | Template gerado pelo Widget Selphi, cifrado com AES256 e tokenizado, enviado em formato Base64. Representa o padrão facial do usuário com a pose frontal mais detectada. |
| `image`                 | string | Não         | Imagem em formato Base64 obtida do registro civil. Torna-se obrigatória se o Template Biométrico registrado (registeredTemplateRaw) não for fornecido.                   |
| `bestImageToken`        | string | **Sim**     | Propriedade **bestImage tokenizada** gerada pelo Widget Selphi no momento da autenticação.                                                                               |
| `template`              | string | Não         | Template Biométrico em formato Base64. Torna-se obrigatória se a bestImage tokenizada (bestImageToken) não for fornecida.                                                |
| `merchantReferenceId`   | string | **Sim**     | Referência do cliente para cada autenticação. Recomenda-se que esse dado não contenha informações sensíveis como PII (informação de identificação pessoal).              |
| `tracking`              | object | Não         | Objeto que representa as informações de tracking necessárias.                                                                                                            |
| `tracking.extraData`    | string | Não         | Token gerado pelo SDK Mobile/Web. Contém informações de tracking tokenizadas com a Plataforma.                                                                           |
| `tracking.operationId`  | string | Não         | Identificador de operação gerado pelo SDK Mobile/Web.                                                                                                                    |

#### Exemplo de solicitação: Com Template Biométrico registrado

```json
{
  "userId": "001",
  "registeredTemplateRaw": "BAIBAQFpWLJtBYBymCoRF...",
  "bestImageToken": "BAIBAQIJTHP8obR2r9ALdDtR5lT...",
  "merchantReferenceId": "authenticate-001",
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "123e4567-e89b-12d3-a456-426614174000"
  }
}
```

#### Exemplo de solicitação: Com imagem do registro civil

```json
{
  "userId": "001",
  "image": "/9j/4AAQ...",
  "bestImageToken": "BAIBAQIJTHP8obR2r9ALdDtR5lT...",
  "merchantReferenceId": "authenticate-001",
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "123e4567-e89b-12d3-a456-426614174000"
  }
}
```

### Respostas

#### `200` Sucesso

#### Parâmetros de resposta

| Parâmetro                       | Tipo    | Descrição                                                                                                        |
| ------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| `serviceResultCode`             | integer | Código que indica o **resultado geral** da execução do serviço. Veja [Service Result Code](#service-result-code) |
| `serviceResultLog`              | string  | Campo descritivo do resultado da execução. Inclui detalhes quando há um erro ou exceção.                         |
| `serviceFacialSimilarityResult` | number  | Valor que indica a **semelhança facial** entre o registeredTemplateRaw e o bestImageToken. **1.0 = 100%**        |
| `merchantReferenceId`           | string  | Referência enviada no corpo da solicitação.                                                                      |
| `registeredTemplateRaw`         | string  | Template Biométrico registrado retornado pelo SDK SelphID para uso em autenticações posteriores.                 |
| `timestamp`                     | string  | Marca de tempo (UTC) da resposta no formato YYYY-MM-DDThh:flag\_mm:ssZ                                           |
| `transactionId`                 | string  | Identificador de transação associado à solicitação processada pela API.                                          |

#### Service Result Code

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         |

#### Código de resultado do serviço: Autenticar usuário

Códigos de resultado específicos do Endpoint `authenticateUser`:

| serviceResultCode | Descrição                                                                | Código HTTP |
| ----------------- | ------------------------------------------------------------------------ | ----------- |
| 0                 | Usuário autenticado com sucesso.                                         | 200         |
| -100              | O parâmetro `registeredTemplateRaw` não coincide com o ID: \[XXX]        | 200         |
| -101              | O parâmetro `bestImageToken` não corresponde a uma pessoa viva.          | 200         |
| -102              | A autenticação do usuário falhou porque o `templateRaw` não corresponde. | 200         |

#### Exemplo de resposta

```json
{
  "merchantReferenceId": "82b0084f-ddec-4415-8d2f-b085b42a0155",
  "serviceResultCode": 0,
  "serviceResultLog": "",
  "serviceFacialSimilarityResult": 0.9946970343589783,
  "timestamp": "2024-10-29T20:29:24Z",
  "transactionId": "531ecbb1-de3d-4907-a737-0db236674e9a",
  "registeredTemplateRaw": "BAIBAQGo+puJyHjfRD8n..."
}
```

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

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

#### `401` Não autorizado

```json
{
  "message": "Não autorizado"
}
```

#### `403` Acesso negado

```json
{
  "Message": "O usuário não está autorizado a acessar este recurso com uma negação explícita"
}
```

#### `502` Gateway inválido

```json
{
  "status": 502,
  "title": "Gateway inválido",
  "detail": "O servidor recebeu uma resposta inválida.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502"
}
```

#### `504` Gateway Timeout

```json
{
  "message": "A solicitação do Endpoint excedeu o tempo limite"
}
```