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

# Autenticação por voz

Este serviço é usado para autenticar uma voz. Recebe um arquivo de áudio e um template de voz, e retorna um booleano indicando se a voz pertence à mesma pessoa que o template de voz, junto com uma pontuação de probabilidade que indica a similaridade entre ambas as vozes.

O áudio pode estar criptografado ou não, e deve estar **codificado em Base64**. O template de voz deve estar **criptografado e codificado em Base64** (obtida do Endpoint de enrollment).

### Endpoint

```
POST /voice/authentication
```

### 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**. Requerido 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                                                                                    |
| ---------- | ------ | ----------- | -------------------------------------------------------------------------------------------- |
| `audio`    | string | **Sim**     | Buffer de áudio **codificado em Base64** (RFC4648).                                          |
| `template` | string | **Sim**     | Template Biométrico **criptografado e codificado em Base64** obtida do enrollment (RFC4648). |

#### Exemplo de solicitação

```json
{
  "audio": "JVBERi0xLjQKJeLjz9MKNSAw IG9iago8P...",
  "template": "BgEBAQI+d368i49ITeoPlmCi5zbYp3kdvTsk6otTOl...."
}
```

### Respostas

#### `200` Sucesso

#### Parâmetros de resposta

| Parâmetro                        | Tipo    | Descrição                                                                                     |
| -------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| `serviceResultCode`              | integer | Código de resultado que indica o estado da operação. **200** significa sucesso.               |
| `serviceResultLog`               | string  | Mensagem de log relacionada ao resultado da operação.                                         |
| `timestamp`                      | string  | Data e hora em que a operação foi concluída.                                                  |
| `serviceTransactionId`           | string  | ID exclusivo de transação para rastrear a operação.                                           |
| `serviceResult.liveness_score`   | number  | Pontuação de detecção de vida.                                                                |
| `serviceResult.match`            | boolean | Indica se a voz **corresponde** ao template.                                                  |
| `serviceResult.matching_score`   | number  | Pontuação de probabilidade que indica a **similaridade entre as vozes** (0-1). **1.0 = 100%** |
| `serviceResult.operation_result` | integer | Código de resultado da operação de autenticação.                                              |
| `serviceResult.tracking_message` | string  | Mensagem de rastreamento da operação.                                                         |
| `serviceResult.tracking_status`  | integer | Código de status de rastreamento.                                                             |
| `serviceTime`                    | string  | Tempo total de execução do serviço **(milissegundos)**.                                       |

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

#### Exemplo de resposta

```json
{
  "serviceResultCode": 200,
  "serviceResultLog": "Service executed ok",
  "timestamp": "2024-07-13T19:43:36Z",
  "serviceTransactionId": "99999999-9999-9999-9999-999999999999",
  "serviceResult": {
    "liveness_score": 0,
    "match": true,
    "matching_score": 1,
    "operation_result": 3,
    "tracking_message": "",
    "tracking_status": -1
  },
  "serviceTime": "1708"
}
```

#### `400` Bad Request

```json
{
  "status": 400,
  "title": "Requisiçã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": "Não autorizado"
}
```

#### `403` Proibido

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

#### `502` Bad Gateway

```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 requisição do Endpoint excedeu o tempo limite"
}
```