> 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/shared-biometric-components/authenticate-facial.md). # Authenticate Facial Servicio que realiza la validación facial entre dos rostros, incluyendo tanto **imágenes abiertas** como **plantillas biométricas**. Este servicio puede utilizarse para realizar las siguientes validaciones: 1. Autenticación facial entre dos **imágenes abiertas**, generadas o no por widgets de FacePhi. 2. Autenticación facial entre dos **plantillas biométricas**, requiere integración del widget Selphi Mobile o Web de FacePhi. 3. Autenticación facial entre una **imagen abierta** y una **plantilla biométrica**, requiere integración del widget Selphi Mobile o Web de FacePhi. 4. Autenticación facial entre el rostro presente en la **foto del documento de identidad (TokenFaceImage)** y una **imagen abierta**, requiere integración del widget SelphID Mobile de FacePhi. 5. Autenticación facial entre el rostro presente en la **foto del documento de identidad (TokenFaceImage)** y una **plantilla biométrica**, requiere integración de los widgets Selphi Mobile y SelphID Mobile de FacePhi. ### Integración * Para las **validaciones tipo 4 y 5**, se requiere la implementación del widget SelphID Mobile para generar la propiedad **TokenFaceImage**. * Para las **validaciones tipo 2, 3 y 5**, se requiere la implementación del widget Selphi Mobile o Web para generar la **propiedad de plantilla biométrica (TemplateRaw)**. ### Endpoint ``` POST /services/authenticateFacial ``` ### Headers | Nombre | Tipo | Requerido | Descripción | | ------------- | ------ | --------- | ------------------------------------------------------------- | | **x-api-key** | string | **Sí** | API key de autorización de acceso. | | **family** | string | No | Valor: **OnBoarding**. 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 | | ---------------------- | ------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `token1` | string | **Sí** | Imagen utilizada como **referencia** para la comparación facial. Dependiendo del método invocado, puede ser el token generado por los widgets SelphID (token de foto del documento), una imagen abierta o una plantilla biométrica tokenizada. | | `token2` | string | **Sí** | Imagen utilizada para la **comparación**. Puede ser una imagen abierta o una plantilla biométrica tokenizada. | | `method` | integer | **Sí** | Indica el **método de comparación** invocado. Ver [Especificación de método](#especificación-de-método). | | `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. | #### Especificación de método | Método | Descripción | Entrada | | ------ | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | | **1** | Autenticación facial mediante **imágenes abiertas** | token1: Base64, token2: Base64 | | **2** | Autenticación facial mediante **plantillas biométricas** | token1: templateRaw, token2: templateRaw | | **3** | Autenticación facial mediante una **imagen abierta** y una **plantilla biométrica** | token1: Base64, token2: templateRaw | | **4** | Autenticación facial mediante el **token generado por el recorte de la foto del documento** y una imagen abierta | token1: tokenFaceImage, token2: Base64 | | **5** | Autenticación facial mediante el **token generado por el recorte de la foto del documento** y una plantilla biométrica | token1: tokenFaceImage, token2: templateRaw | #### Ejemplo de solicitud ```json { "token1": "BAMBAQLNHJoWGPjfeuDIzDXdZuP...", "token2": "BAMBAQLNHJoWGPjfeuDIzDXdZuP...", "method": 1, "tracking": { "extraData": "BQABAQG2gBNjuHN4kLmPqYf7R...", "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 del servicio. Incluye detalles cuando hay un error o excepción en el módulo. | | `serviceTime` | string | Tiempo total de procesamiento **(milisegundos)**. | | `serviceTransactionId` | string | Identificador de transacción asociado a la solicitud procesada por la API. | | `serviceFacialAuthenticationHash` | string | Hash de integridad de la plantilla biométrica utilizada en una autenticación facial positiva o incierta. **Solo aplicable en los métodos 2, 3 y 5.** | | `serviceFacialAuthenticationResult` | integer | Código que indica el **resultado de la coincidencia facial**. Ver [Service Facial Authentication Result](#service-facial-authentication-result) | | `serviceFacialSimilarityResult` | number | Valor que indica la **similitud facial** entre el rostro en la foto del documento de identidad y el selfie tomado por el usuario. **1.0 = 100%** | #### 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 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: Positive ```json { "serviceResultCode": 0, "serviceResultLog": "Positive", "serviceTime": "516", "serviceTransactionId": "a29cbe15-2b68-495f-b7eb-be985b21c486", "serviceFacialAuthenticationHash": "47D0ACDCF08C348469C2F512BB59216B46DCD9B253822ED0E4EEAFCEB76AADD5AEF20CA31EC52D03EB290EBC91A6AD65FB0416F9EB2164D3854932153074289E", "serviceFacialAuthenticationResult": 3, "serviceFacialSimilarityResult": 0.99153554 } ``` #### Ejemplo de respuesta: Negative ```json { "serviceResultCode": 0, "serviceResultLog": "Negative", "serviceTime": "502", "serviceTransactionId": "e96e85a4-3f94-4000-b639-15c4f18c345b", "serviceFacialAuthenticationHash": "09B9A4097E3642ADEDB665BA2E15B096FFB65A039E0D7137D0AD38666F90A010624C26867E6A7DB8346385610CC9FEDE435C3CC6A2AC9B008DD98C6EFE8C42E7", "serviceFacialAuthenticationResult": 1, "serviceFacialSimilarityResult": 0.01190000 } ``` #### `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" } ```