> 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/api-rest/identity-api/identity-api-reference/authentication/voice-authentication.md).

# Voice Authentication

Este servicio se utiliza para autenticar una voz. Recibe un archivo de audio y una plantilla de voz, y devuelve un booleano indicando si la voz pertenece a la misma persona que la plantilla de voz, junto con una puntuación de probabilidad que indica la similitud entre ambas voces.

El audio puede estar cifrado o no, y debe estar **codificado en Base64**. La plantilla de voz debe estar **cifrada y codificada en Base64** (obtenida del endpoint de enrollment).

### Endpoint

```
POST /voice/authentication
```

### Headers

| Nombre        | Tipo   | Requerido | Descripción                                                       |
| ------------- | ------ | --------- | ----------------------------------------------------------------- |
| **x-api-key** | string | **Sí**    | API key de autorización de acceso.                                |
| **family**    | string | No        | Valor: **Authentication**. Requerido con el servicio de tracking. |

{% hint style="info" %}
Todas las llamadas a los Endpoints para tracking con **Identity Platform** deben contener el header `family`.
{% endhint %}

### Cuerpo de la solicitud

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

#### Parámetros

| Parámetro  | Tipo   | Requerido | Descripción                                                                                |
| ---------- | ------ | --------- | ------------------------------------------------------------------------------------------ |
| `audio`    | string | **Sí**    | Buffer de audio **codificado en Base64** (RFC4648).                                        |
| `template` | string | **Sí**    | Plantilla biométrica **cifrada y codificada en Base64** obtenida del enrollment (RFC4648). |

#### Ejemplo de solicitud

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

### Respuestas

#### `200` Éxito

#### Parámetros de respuesta

| Parámetro                        | Tipo    | Descripción                                                                                  |
| -------------------------------- | ------- | -------------------------------------------------------------------------------------------- |
| `serviceResultCode`              | integer | Código de resultado que indica el estado de la operación. **200** significa éxito.           |
| `serviceResultLog`               | string  | Mensaje de log relacionado con el resultado de la operación.                                 |
| `timestamp`                      | string  | Fecha y hora en que se completó la operación.                                                |
| `serviceTransactionId`           | string  | ID único de transacción para rastrear la operación.                                          |
| `serviceResult.liveness_score`   | number  | Puntuación de detección de vida.                                                             |
| `serviceResult.match`            | boolean | Indica si la voz **coincide** con la plantilla.                                              |
| `serviceResult.matching_score`   | number  | Puntuación de probabilidad que indica la **similitud entre las voces** (0-1). **1.0 = 100%** |
| `serviceResult.operation_result` | integer | Código de resultado de la operación de autenticación.                                        |
| `serviceResult.tracking_message` | string  | Mensaje de seguimiento de la operación.                                                      |
| `serviceResult.tracking_status`  | integer | Código de estado de seguimiento.                                                             |
| `serviceTime`                    | string  | Tiempo total de ejecución del servicio **(milisegundos)**.                                   |

#### Service Result Code

El `serviceResultCode` indica el resultado general de la ejecución del servicio:

| serviceResultCode | Descripción                                                                          | Código HTTP |
| ----------------- | ------------------------------------------------------------------------------------ | ----------- |
| 0                 | La ejecución del servicio fue exitosa, el módulo procesó la solicitud correctamente. | 200         |

#### Ejemplo de respuesta

```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": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}
```

#### `401` Unauthorized

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

#### `403` Forbidden

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

#### `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` Gateway Timeout

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