> 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/authenticate-user-v2.md). # Authenticate User V2 Este servicio valida tanto la prueba de vida como la autenticación facial. Compara la plantilla biométrica, 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 verificación de vida, el usuario se autentica exitosamente. ### Integración Requiere la implementación del **widget Selphi Mobile** o del **widget Selphi Web** para generar el **bestImageToken** y la **plantilla biométrica (TemplateRaw)**. ### Endpoint ``` POST /services/authenticateUser/v2 ``` ### 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 | | ----------------------- | ------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `userId` | string | **Sí** | Identificador único del usuario. Debe ser persistido y asociado con la plantilla biométrica correspondiente. Necesita al menos dos dígitos. | | `registeredTemplateRaw` | string | **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 | No | Imagen en formato Base64 obtenida del registro civil. Se vuelve obligatoria si no se proporciona la plantilla biométrica registrada (registeredTemplateRaw). | | `bestImageToken` | string | **Sí** | Propiedad **bestImage tokenizada** generada por el widget Selphi en el momento de la autenticación. | | `template` | string | No | 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 este dato no contenga información sensible como PII (información de identificación personal). | | `tracking` | object | No | Objeto que representa la información de seguimiento necesaria. | | `tracking.extraData` | string | No | Token generado por el SDK Mobile/Web. Contiene información de seguimiento tokenizada con la Plataforma. | | `tracking.operationId` | string | No | Identificador de operación generado por el SDK Mobile/Web. | #### Ejemplo de solicitud: Con plantilla biométrica registrada ```json { "userId": "001", "registeredTemplateRaw": "BAIBAQFpWLJtBYBymCoRF...", "bestImageToken": "BAIBAQIJTHP8obR2r9ALdDtR5lT...", "merchantReferenceId": "authenticate-001", "tracking": { "extraData": "BQABAQG2gBNjuHN...", "operationId": "123e4567-e89b-12d3-a456-426614174000" } } ``` #### Ejemplo de solicitud: Con imagen del registro civil ```json { "userId": "001", "image": "/9j/4AAQ...", "bestImageToken": "BAIBAQIJTHP8obR2r9ALdDtR5lT...", "merchantReferenceId": "authenticate-001", "tracking": { "extraData": "BQABAQG2gBNjuHN...", "operationId": "123e4567-e89b-12d3-a456-426614174000" } } ``` ### Respuestas #### `200` Éxito #### Parámetros de respuesta | Parámetro | Tipo | Descripción | | ----------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `serviceResultCode` | integer | Código que indica el **resultado general** de la ejecución del servicio. Ver [Service Result Code](#service-result-code) | | `serviceResultLog` | string | Campo descriptivo del resultado de la ejecución. Incluye detalles cuando hay un error o excepción. Si es exitoso, indica la descripción del código de resultado. | | `serviceFacialSimilarityResult` | number | Valor que indica la **similitud facial** entre el registeredTemplateRaw y el bestImageToken. **1.0 = 100%** | | `serviceFacialAuthenticationLog` | string | Campo descriptivo del resultado 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 [Service Facial Authentication Result](#service-facial-authentication-result) | | `serviceLivenessResult` | integer | Código que indica el **resultado de la prueba de vida pasiva**. Ver [Service Liveness Result](#service-liveness-result) | | `serviceLivenessLog` | string | Campo descriptivo del resultado de la verificación de vida pasiva. Incluye detalles cuando hay un error o excepción. | | `merchantReferenceId` | string | Referencia enviada en el cuerpo de la solicitud. | | `registeredTemplateRaw` | string | Plantilla biométrica registrada devuelta por el SDK SelphID para uso en autenticaciones posteriores. | | `timestamp` | string | Marca de tiempo (UTC) de la respuesta en formato YYYY-MM-DDThh:flag\_mm:ssZ | | `transactionId` | string | Identificador de transacción asociado a la solicitud procesada por la API. | #### 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 | #### Service Liveness Result El `serviceLivenessResult` indica el resultado de la evaluación de la prueba de vida pasiva: | Código | Resultado | Descripción | | ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | | 0 | None | No se pudo evaluar la prueba de vida. | | 1 | Spoof | DEPRECADO. Usar 'NoLive' en su lugar. | | 2 | Uncertain | DEPRECADO | | 3 | Live | Se asume que el sujeto está vivo. | | 4 | NoneBecauseBadQuality | No se pudo evaluar la prueba de vida debido a la mala calidad de la imagen. | | 5 | NoneBecauseFaceTooClose | No se pudo evaluar la prueba de vida porque los rostros detectados están muy cerca de los bordes. | | 6 | NoneBecauseFaceNotFound | No se pudo evaluar la prueba de vida porque no se detectaron rostros. | | 7 | NoneBecauseFaceTooSmall | No se pudo evaluar la prueba de vida porque los rostros detectados son muy pequeños. | | 8 | NoneBecauseAngleTooLarge | No se pudo evaluar la prueba de vida porque el ángulo entre rostros excede el límite permitido. | | 9 | NoneBecauseImageDataError | No se pudo evaluar la prueba de vida debido a errores en el formato de la imagen. | | 10 | NoneBecauseInternalError | No se pudo evaluar la prueba de vida debido a un error interno. | | 11 | NoneBecauseImagePreprocessError | No se pudo evaluar la prueba de vida debido a un error en el preprocesamiento de la imagen. | | 12 | NoneBecauseTooManyFaces | No se pudo evaluar la prueba de vida porque se detectaron demasiados rostros en la imagen. | | 13 | NoneBecauseFaceTooCloseToBorder | No se pudo evaluar la prueba de vida porque el rostro está muy cerca del borde. | | 14 | NoneBecauseFaceCropped | No se pudo evaluar la prueba de vida porque el rostro está recortado. | | 15 | NoneBecauseLicenseError | No se pudo evaluar la prueba de vida debido a un error de licencia. | | 16 | NoneBecauseFaceOccluded | No se pudo evaluar la prueba de vida porque el rostro está ocluido. | | 17 | NoLive | No se detectó vida. | | 18 | NoneBecauseEyesClosed | No se pudo evaluar la prueba de vida porque los ojos de la persona están cerrados. | #### Service Facial Authentication Result El `serviceFacialAuthenticationResult` indica el resultado de las operaciones de coincidencia facial: | Código | Resultado | Descripción | | ------ | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 0 | NONE | No se pudo realizar la verificación facial. | | 1 | NEGATIVE | El proceso se ejecutó correctamente. La comparación del patrón facial de los rostros no coincide. | | 3 | POSITIVE | El proceso se ejecutó correctamente. La comparación del patrón facial de los rostros es positiva. El valor de `serviceFacialSimilarityResult` indica el % de similitud entre las imágenes comparadas. | | 4 | NONE BECAUSE POSE EXCEED | No se pudo realizar la verificación facial debido a la posición del rostro. | | 5 | NONE BECAUSE INVALID EXTRACTIONS | No se pudo realizar la verificación facial debido a problemas en la extracción del patrón facial. | #### 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..." } ``` #### `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" } ```