Autenticación de usuario v2

/authenticateUser v2

Este servicio valida tanto la prueba de vida (liveness) como la autenticación facial. Compara la plantilla biométrica (templateRaw), que fue previamente validada y almacenada en el repositorio de datos del cliente durante el proceso de Onboarding, con un bestImageToken generado en el momento de la autenticación.

Funcionalidad

• Primera Llamada: Establece un userId único para el usuario.

• Autenticación: En cada intento de autenticación, se envía el userId junto con la plantilla biométrica registrada. Esta plantilla se compara con la imagen tokenizada actual (bestImageToken). Si hay coincidencia y se supera la prueba de vida, el usuario se autentica exitosamente.

Solicitud:

bash

curl --location '{IDENTITY_API_BASE_URL}/services/authenticateUser/v2' \
--header 'x-api-key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "userId": "001",
    "registeredTemplateRaw": "BAIBAQFpWLJtBYBymCoRF…",
    "bestImageToken": "BAIBAQIJTHP8obR2r9ALdDtR5lT…",
    "merchantReferenceId": "authenticate-001",
    "tracking": {
        "extraData": "BQABAQG2gBNjuHN...",
        "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
    }
}'

Parámetros de la solicitud:

Parámetro	Tipo (Contenido)	Requerido	Descripción
userId	String	Sí	Identificador único para el usuario. Debe persistirse y asociarse con la plantilla biométrica correspondiente. Necesita tener al menos dos dígitos.
registeredTemplateRaw	String (Base64)	Sí	Plantilla generada por el widget Selphi, cifrada con AES256 y tokenizada, enviada en formato Base64. Representa el patrón facial del usuario con la pose frontal más detectada.
image	String (Base64)	No	[Opcional] Imagen en formato Base64 obtenida del registro civil. Se vuelve obligatoria si no se proporciona la plantilla biométrica registrada ("registeredTemplateRaw").
bestImageToken	String (Base64)	Sí	Propiedad bestImage tokenizada generada por el widget Selphi en el momento de la autenticación.
template	String (Base64)	No	[Opcional] Plantilla biométrica en formato Base64. Se vuelve obligatoria si no se proporciona la bestImage tokenizada ("bestImageToken").
merchantReferenceId	String	Sí	Referencia del cliente para cada autenticación. Se recomienda que estos datos no contengan información sensible como PII (información de identificación personal).
tracking	JSON Object	No	Objeto que representa la información de seguimiento necesaria.
extraData	String (Base64)	No	Token generado por el SDK móvil/web. Contiene información de seguimiento tokenizada.
operationId	String (Base64)	No	Identificador de operación generado por el SDK móvil/web.

Ejemplo de cuerpo con registeredTemplateRaw:

json

{
    "userId": "001",
    "registeredTemplateRaw": "BAIBAQFpWLJtBYBymCoRF…",
    "bestImageToken": "BAIBAQIJTHP8obR2r9ALdDtR5lT…",
    "merchantReferenceId": "authenticate-001",
    "tracking": {
        "extraData": "BQABAQG2gBNjuHN...",
        "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
    }
}

Ejemplo de Cuerpo con image:

json

{
    "userId": "001",
    "image": "/9j/4AAQ...",
    "bestImageToken": "BAIBAQIJTHP8obR2r9ALdDtR5lT…",
    "merchantReferenceId": "authenticate-001",
    "tracking": {
        "extraData": "BQABAQG2gBNjuHN...",
        "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
    }
}

Campos de la respuesta:

Identificador	Tipo	Descripción
timestamp	String	Marca de tiempo (UTC) de la respuesta en el formato: YYYY-MM-DDThh:mm:ss.SSSZ
transactionId	String	Identificador de transacción asociado a la solicitud procesada por la API.
serviceResultCode	Integer	Código que indica el resultado general de la ejecución del servicio. Ver Tabla 1 - Código de Resultado del Servicio
serviceResultLog	String	Campo descriptivo del resultado de la ejecución cuando hay un error o excepción. Si es exitoso, indica la descripción del código de resultado.
serviceFacialSimilarityResult	Float	Valor que indica la similitud facial entre el registeredTemplateRaw y el bestImageToken. 1.0 = 100%.
serviceFacialAuthenticationLog	String	Campo descriptivo del resultado de la ejecución de la autenticación facial. Incluye detalles cuando hay un error o excepción en el módulo.
serviceFacialAuthenticationResult	Integer	Código que indica el resultado de la autenticación facial. Ver Tabla 2 - Resultado de Autenticación Facial del Servicio
serviceLivenessResult	Integer	Código que indica el resultado de la evaluación de la prueba de vida pasiva. Ver Tabla 3 - Resultado de Prueba de Vida del Servicio
serviceLivenessLog	String	Campo descriptivo del resultado de la ejecución de la prueba de vida pasiva. Incluye detalles cuando hay un error o excepción.
merchantReferenceId	String	Referencia enviada en el cuerpo de la solicitud.
registeredTemplateRaw	String	[Opcional] Plantilla biométrica registrada devuelta por el extracto del SDK de SelphID para usar en autenticaciones posteriores.

Ejemplo de Respuesta:

json

{
    "merchantReferenceId": "82b0084f-ddec-4415-8d2f-b085b42a0155",
    "serviceResultCode": 0,
    "serviceResultLog": "",
    "serviceFacialSimilarityResult": 0.9946970343589783,
    "serviceFacialAuthenticationLog": "Positive",
    "serviceFacialAuthenticationResult": 3,
    "serviceLivenessLog": "Live",
    "serviceLivenessResult": 3,
    "timestamp": "2024-10-29T20:29:24Z",
    "transactionId": "531ecbb1-de3d-4907-a737-0db236674e9a",
    "registeredTemplateRaw": "BAIBAQGo+puJyHjfRD8n"
}

---

Código de Resultado del Servicio /authenticateUser

serviceResultCode	Descripción en Español	Código HTTP
0	Usuario autenticado exitosamente.	200
-100	El parámetro registeredTemplateRaw no coincide con el ID: [XXX]	200
-101	El parámetro bestImageToken no coincide con una persona real (prueba de vida).	200
-102	La autenticación del usuario falló debido a que la templateRaw no coincide.	200