> 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 Biométrico, e retorna um booleano indicando se a voz pertence à mesma pessoa que o modelo 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 Biométrico deve estar **criptografado e codificado em Base64** (obtida do Endpoint de cadastro).

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

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

#### Exemplo de resposta

```json
{
  "serviceResultCode": 200,
  "serviceResultLog": "Serviço executado com sucesso",
  "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` Requisição inválida

```json
{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}
```

#### `401` Não autorizado

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

#### `403` Acesso negado

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

#### `502` Gateway inválido

```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` Tempo limite do gateway

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