Liveness

POST

  https://api.apptenticate.com/api/v3.2/biometrics/liveness/

Autenticación

Usa tu JWT obtenido del proceso de autenticación para hacer peticiones a este endpoint.

La respuesta sera 401 unauthorized si el JWT se encuentra vencido. En dicho caso deberás obtener un nuevo JWT.

---

Este endpoint es el punto de entrada para todas las peticiones dirigidas al servicio Liveness, el cual permite procesar selfies y clasificarlas como spoofing o reales.

Spoofing: Ataque a un sistema biométrico facial que utiliza una imagen para engañar al proceso de autenticación.

tip

Si tienen activos los servicios de Biometría Apptenticate o Biometría SIB, pueden hacer una sola petición a los endpoints de biometría para ambos servicios, optimizando las solicitudes.

Datos de la petición

Para realizar una petición a este endpoint se pueden enviar los siguientes parámetros en el body de la misma:

Name	Tipo	Descripción	Requerido
selfie	file	Imagen del selfie de la persona. El endpoint admite cualquier formato de imagen valido (PNG, JPG, JPEG, etc.)	true
return_id	boolean	Booleano que indica si se desea obtener el ID de la transacción.	false
device	string	Dispositivo desde el cual se está realizando la prueba de vida. DESKTOP, IOS o ANDROID.	false
details	boolean	Booleano que indica si se desea obtener detalles de la prueba de vida.	false

Parámetros de respuesta

Si se elige visualizar los details junto al response, se obtendrán los siguientes datos:

Formato de respuesta: JSON

data: {
    "api_response": {
        "score": 2.656599,
        "quality": 0.8511556,
        "liveness": 0.9344166
    },
}

score: Cuanto mayor sea la puntuación, mayor será la liveness de la imagen. El valor no está limitado y puede ser usado con fines de calibración.

quality: Define que tan "apropiada" es la imagen para la comprobación de liveness. El valor puede estar en el rango [0,1]. Las imágenes con valores de calidad inferiores a 0,5 serán rechazadas automáticamente por el servicio.

liveness: Define que tan "real" es la imagen o si se trata de spoofing. El valor puede estar en el rango [0,1]. Las imágenes con valores de liveness inferiores a 0,5 serán rechazadas automáticamente por el servicio.

Ejemplo de petición

Shell

Request

curl --location 'https://api.apptenticate.com/api/v3.2/biometrics/liveness/' \
--form 'selfie="<selfie>"' \
--form 'return_id="<return_id>"' \
--form 'device="<device>"' \
--form 'details="<details>"'

Node

Instalación

npm install axios form-data

Request

import axios from 'axios'
import FormData from 'form-data'

async function makeRequest() {
  let data = new FormData()
  let selfieStream = fs.createReadStream('<path_to_selfie_file>')

  data.append('selfie', selfieStream)
  data.append('return_id', '<return_id>')
  data.append('device', '<device>')
  data.append('details', '<details>')

  try {
    const { data } = await axios.post(
      'https://api.apptenticate.com/api/v3.2/biometrics/liveness/',
      data,
      {
        headers: data.getHeaders(),
        maxBodyLength: Infinity
      }
    )
    return JSON.stringify(data)
  } catch (error) {
    console.log(error)
  }
}

makeRequest()

Python

Instalación

python -m pip install requests

Request

import requests

url = "https://api.apptenticate.com/api/v3.2/biometrics/liveness/"

data = {
    "return_id": "<return_id>",
    "device": "<device>",
    "details": "<details>"
}

file = {"selfie": open("<path_to_selfie_file>", "rb")}  # Reemplace <path_to_selfie_file> con la ruta al archivo de selfie

response = requests.post(url, data=data, files=file)

if response.status_code == 200:
    print(response.json())
else:
    print(f"Request failed with status code {response.status_code}")

Ejemplos de respuestas

Este sera el formato de la respuesta obtenida al enviar todos los parámetros:

Formato de respuesta: JSON

data: {
    "valid": true,
    "api_response": {
        "score": 2.656599,
        "quality": 0.8511556,
        "liveness": 0.9344166
    },
    "id": 1111
}

Al dejar de enviar el parámetro return_id en la petición, el formato de la respuesta sera el siguiente:

Formato de respuesta: JSON

data: {
    "valid": true,
    "api_response": {
        "score": 2.656599,
        "quality": 0.8511556,
        "liveness": 0.9344166
    }
}

Si adicionalmente se omite el parámetro details en la petición, el formato de la respuesta sera el siguiente:

Formato de respuesta: JSON

data: {
    "valid": true
}

Si el servicio detecta cualquier inconveniente en la imagen enviada, el formato de la respuesta sera el siguiente:

Formato de respuesta: JSON

data: {
    "valid": false,
    "message": "Rostro muy reducido en pixeles",
    "error_code": 706
}

Códigos de rechazo

En caso de que la petición no sea exitosa, se enviará un código de rechazo en la respuesta. Los códigos de rechazo posibles son:

Código	Mensaje
700	Rostro demasiado cerca.
701	Rostro demasiado cerca de los bordes.
702	Rostro incompleto.
703	Rostro obstruido.
704	Rostro no detectado
705	Demasiados rostros.
706	Rostro muy reducido en pixeles
707	Angulo de rostro incorrecto.
708	Error al leer imagen.
709	Error al procesar imagen.
710	Error al predecir bordes de rostro.
711	Error interno de motor de prueba de vida
712	Error desconocido.
713	Calidad de imagen para prueba de vida no aceptable.
714	Condiciones mínimas de imagen para prueba de vida no alcanzadas.
715	Puntaje mínimo para prueba de vida no alcanzado.
716	Se detectó que los ojos estaban cerrados.