> 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/onboarding/identity-validation-v2.md). # Identity Validation V2 Este servicio realiza tanto la **validación de vida** como la **comparación facial** entre dos rostros, ya sea proporcionados como imágenes abiertas o como parámetros tokenizados. Soporta dos tipos de validaciones faciales, dependiendo del widget integrado. ### Integración * Para la **validación tipo 3**, se requiere una **imagen en formato abierto** del frente de la cédula de identidad, donde se encuentra el rostro. * Para la **validación tipo 5**, es necesario implementar el **widget SelphID Mobile** para generar la propiedad **TokenFaceImage**. ### Endpoint ``` POST /onboarding/v2/identity ``` ### 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. Puede ser una imagen base64 o **TokenFaceImage**, dependiendo del método. | | `bestImageToken` | string | **Sí** | Propiedad **bestImage tokenizada** generada por el widget Selphi y tokenizada mediante la función nativa. | | `method` | string | **Sí** | Indica el **método de comparación** invocado. Ver [Especificación de método](#especificacion-de-metodo). | | `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 | | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | **"3"** | Autenticación facial mediante una **imagen abierta** y **bestImage tokenizada** (Base64 & bestImageToken) | | **"5"** | Autenticación facial mediante el **token generado por el recorte de la foto del documento** y **bestImage tokenizada** (tokenFaceImage & bestImageToken) | #### Ejemplo de solicitud ```json { "token1": "/9j/4AAQSkZJRgABAQAASAB...", "bestImageToken": "BAMBAQLNHJoWGPj...", "method": "3", "tracking": { "extraData": "BQABAQG2gBNjuHN4kLmPqYf7R...", "operationId": "123e4567-e89b-12d3-a456-426614174000" } } ``` ### Respuestas #### `200` Éxito #### Parámetros de respuesta | Parámetro | Tipo | Descripción | | -------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `serviceTransactionId` | string | Identificador de transacción asociado a la solicitud de la API. | | `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. Proporciona detalles de errores o excepciones cuando ocurren. | | `serviceTime` | string | Campo que indica el tiempo de procesamiento **(milisegundos)**. | | `facialAuthenticationResult` | integer | Código que indica el **resultado de la coincidencia facial**. Ver [Service Facial Authentication Result](#service-facial-authentication-result) | | `facialAuthenticationLog` | string | Campo descriptivo del resultado de la coincidencia facial. | | `facialAuthenticationSimilarity` | number | Valor que indica la **similitud facial** entre la foto del documento y el selfie tomado por el usuario. **1.0 = 100%** | | `passiveLivenessResult` | integer | Código que indica el **resultado de la prueba de vida pasiva**. Ver [Service Liveness Result](#service-liveness-result) | | `passiveLivenessLog` | string | Campo descriptivo del resultado de la prueba de vida pasiva. | #### 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 { "serviceTransactionId": "2db602ee-3564-4304-af95-92a52eaae12d", "serviceResultCode": 0, "serviceResultLog": "[identity] Service executed ok", "serviceTime": "2235", "facialAuthenticationResult": 3, "facialAuthenticationLog": "Positive", "facialAuthenticationSimilarity": 0.99214232, "passiveLivenessResult": 3, "passiveLivenessLog": "Live" } ``` #### `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" } ```