Liveness Plus

POST

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

Autenticación

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

La respuesta será 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:

Nombre	Tipo	Descripción	Contenido
encrypted_file	binary	Paquete cifrado con los metadatos de la imagen que captura.	True
details	boolean	Booleano que indica si se desea obtener detalles de la prueba de vida.	False
return_id	boolean	Booleano que indica si se desea obtener el ID de la transacción.	False

Parámetros de respuesta

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

Formato de respuesta: JSON

{
    "api_response": {
        "face_liveness": {
            "probability": 0.9859461
        },
        "capture_liveness": {
            "score": 1.1050358,
            "probability": 1.0
        }
    }
}

face_liveness [probability]: 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.

capture_liveness [probability]: Define si la captura de la probabilidad de vida es 0 (ataque) a 1 (vivo). Las imágenes con valores 0 serán rechazadas automáticamente por el servicio.

capture_liveness [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.

Ejemplo de petición y Librería de captura

La librería de captura controla el proceso de captura del cliente y pone a disposición el objeto encrypted_file para el llamado al servicio liveness-plus. El servidor descomprime el paquete para detectar ataques de inyección y de presentación.

Existen 3 tipos de librerías de captura:

• Librería de captura web
• Librería de captura Android
• Librería de captura iOS

Nota: Consultar al equipo técnico por ejemplos orientados en las siguientes tecnologías, Vue, React, HTML, Angular.

1 - Modo de uso de la librería de captura web

Pasos generales de instalación y configuración.

• Instale el paquete idlive-face-capture-web.tgz. Debe ser proporcionado por Darien Technology.
  • npm i idlive-face-capture-web file:./idlive-face-capture-web.tgz
• Importe el componente.
  • import 'idlive-face-capture-web';
• Obtener el componente.
  • const idliveFaceCapture = document.querySelector('idlive-face-capture');

Ejemplo de petición

Servicio Biometría Panamá

Utilice el evento capture para obtener un archivo cifrado y la foto para su verificación después de la captura.

idliveFaceCapture.addEventListener('capture', (event) => {
    const { photo, encryptedFile } = event.detail[0];
    sendEncryptedFileToServer(photo, encryptedFile)
});

Implementar el método sendEncryptedFileToServer para interactuar con el servidor.

const sendEncryptedFileToServer = (photo, encryptedFile) => {

    const serverUrl = 'https://api.apptenticate.com';
    
    const formData = new FormData();          
    formData.append('selfie', photo,'selfie.jpeg' );
    formData.append('encrypted_file', encryptedFile);
    formData.append('return_id', true);
    formData.append('citizen_id', '7-708-214');
    formData.append('device', 'DESKTOP');


    return fetch(`${serverUrl}/api/v3/biometrics/nationals/`, {
        method: "post",
        headers: {
            'Authorization': `Bearer ${token}`
        },
        body: formData
    })
    .then(response => response.json())
    .then(result => console.log(result))
    .catch(e => { console.error(e) })
    .finally();
}

Servicio Biometría Apptenticate

Utilice el evento capture para obtener un archivo cifrado y la foto para su verificación después de la captura.

idliveFaceCapture.addEventListener('capture', (event) => {
    const { photo, encryptedFile } = event.detail[0];
    sendEncryptedFileToServer(photo, encryptedFile)
});

Implementar el método sendEncryptedFileToServer para interactuar con el servidor.

const sendEncryptedFileToServer = (photo, encryptedFile) => {

    const serverUrl = 'https://api.apptenticate.com';

    const formData = new FormData();
    formData.append('frontside', blob, 'frontside.jpeg');
    formData.append('selfie', photo, 'selfie.jpeg');            
    formData.append('encrypted_file', encryptedFile);
    formData.append('return_id', true);
    formData.append('document_type', 'identification_card');


    return fetch(`${serverUrl}/api/v3/biometrics/foreigns/`, {
        method: "post",
        headers: {
            'Authorization': `Bearer ${token}`
        },
        body: formData
    })
    .then(response => response.json())
    .then(result => console.log(result))
    .catch(e => { console.error(e) })
    .finally();
}

Liveness-plus

Utilice el evento capture para obtener un archivo cifrado para su verificación después de capturar la foto.

idliveFaceCapture.addEventListener('capture', (event) => {
    const { encryptedFile } = event.detail[0];
    sendEncryptedFileToServer(encryptedFile) 
});

Implementar un método sendEncryptedFileToServer para interactuar con el servidor.

const sendEncryptedFileToServer = (encryptedFile) => {

    const serverUrl = 'https://api.apptenticate.com';

    const formData = new FormData();
    formData.append('encrypted_file', encryptedFile);
    
    return fetch(`${serverUrl}/api/v3/biometrics/liveness/`, {
        method: "post",
        headers: {
            'Authorization': `Bearer ${token}`
        },
        body: formData
    })
    .then(response => response.json())
    .then(result => console.log(result))
    .catch(e => { console.error(e) })
    .finally();
}

Ejemplo de respuestas

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

{
    "valid": true,
    "api_response": {
        "face_liveness": {
            "probability": 0.9859461
        },
        "capture_liveness": {
            "score": 1.1050358,
            "probability": 1.0
        }
    },
    "id": 284
}

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

{
    "valid": true,
    "api_response": {
        "face_liveness": {
            "probability": 0.9859461
        },
        "capture_liveness": {
            "score": 1.1050358,
            "probability": 1.0
        }
    }
}

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

{
    "valid": true
}

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

{
    "valid": false,
    "error_code": 715,
    "message": "Ataque detectado en la imagen enviada.",
    "error_details": {
        "capture_liveness": "Para un resultado positivo debe obtener 1, valor alcanzado: 0.0.",
        "api_response": {
            "face_liveness": {
                "probability": 0.9607433
            },
            "capture_liveness": {
                "score": 1.0851271,
                "probability": 0.0
            }
        }
    },
    "id": 287
}

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	Ataque detectado en la imagen enviada.