> 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/morphology/document-pad-diagnostic.md). # Document PAD Diagnostic Servicio que permite verificar si el soporte de un documento de identidad es **genuino o no** mediante el análisis de su imagen, con el fin de detectar **ataques de presentación** dirigidos al robo de identidad. El resultado de la validación puede retornar los siguientes valores: * **Credible**: El documento es genuino. * **Doubtful**: No se puede asegurar si el documento es genuino. * **Spoof**: El documento parece no ser genuino. * **Error**: El proceso de validación encontró un error. El resultado se proporciona en el campo **`decision`** de la respuesta del servicio, junto con el campo **`reason`** que especifica la causa de las validaciones insatisfactorias. ### Requisitos de imagen #### Requisitos mínimos * Imágenes HD, resolución mínima: **720px** * Píxeles que muestren el fondo alrededor del documento de al menos **5% de su ancho** * Nivel mínimo de compresión: **JPEG 70** * El texto del documento debe ser legible por un OCR #### Requisitos recomendados * Imágenes FullHD, resolución mínima: **1080px** * Documento centrado en la imagen y que ocupe más del **5% del documento** * Sin compresión, con formatos como **PNG** * Foto bien iluminada sin desenfoque ni reflejos de luz ### Endpoint ``` POST /verify/pad/diagnostic ``` ### 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 | | ---------------------- | ------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `frontSideImage` | string | **Sí** | Imagen codificada en **Base64** del lado frontal del documento a validar. | | `backSideImage` | string | **Sí** | Imagen codificada en **Base64** del lado posterior del documento a validar. | | `face` | string | No | Imagen codificada en **Base64** del rostro de la persona a validar (opcional). | | `tokenized` | boolean | **Sí** | Define si las imágenes se envían en **formato tokenizado** o en formato plano. | | `countryCode` | string | **Sí** | Código **ISO Alpha-3** del país emisor del documento de identidad. | | `idType` | string | **Sí** | Tipo de documento a validar. Valores posibles: `PASSPORT`, `ID_CARD`, `RESIDENCE_PERMIT`, `DRIVERS_LICENSE`, `DRIVING_LICENSE`, `VISA` | | `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 ```json { "frontSideImage": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==", "backSideImage": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==", "face": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==", "tokenized": false, "countryCode": "ESP", "idType": "ID_CARD", "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 procesada por la API. | | `serviceResultCode` | integer | Código que indica el **resultado general** de la ejecución del servicio. | | `serviceResultLog` | string | Campo descriptivo del resultado de la ejecución. | | `timestamp` | string | Marca de tiempo (UTC) de la respuesta en formato **ISO 8601**. | | `serviceResult` | object | Objeto con el resultado de la validación. Ver tabla a continuación. | | `serviceDocumentData` | string | Cadena JSON con los datos extraídos por OCR del documento de identidad. | | `serviceTime` | string | Tiempo de procesamiento **(milisegundos)**. | #### Parámetros de respuesta — `serviceResult.result` | Parámetro | Tipo | Nullable | Descripción | | ---------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `decision` | string | No | Decisión de la validación. Valores posibles: `Credible`, `Doubtful`, `Spoof`, `Error`. Ver [PAD Diagnostic Validation Results](#pad-diagnostic-validation-results). | | `reason` | string | Sí | Motivo del rechazo (presente cuando la decisión no es Credible). Ver [PAD Diagnostic Rejection Reasons](#pad-diagnostic-rejection-reasons). | | `IQA` | object | Sí | Datos de evaluación de calidad de imagen (Image Quality Assessment). | #### Parámetros de respuesta — `serviceResult` (adicionales) | Parámetro | Tipo | Descripción | | ------------------------- | ------ | ---------------------------------------------------- | | `api_version` | string | Versión de la API utilizada para el procesamiento. | | `processing_modules_time` | string | Tiempo de ejecución de los módulos de procesamiento. | #### 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 | #### PAD Diagnostic Validation Results El servicio de diagnóstico PAD (Presentation Attack Detection) retorna los resultados de validación en el campo `decision`: | decision | Descripción | | ---------- | ------------------------------------------------ | | `Credible` | El documento es genuino. | | `Doubtful` | No se puede asegurar si el documento es genuino. | | `Spoof` | El documento parece no ser genuino. | | `Error` | El proceso de validación encontró un error. | #### PAD Diagnostic Rejection Reasons Cuando el resultado de la validación no es satisfactorio, el campo `reason` proporciona detalles específicos: | reason | Descripción | | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `Screen_Replay_Attack` | Un atacante presenta una imagen o video de un documento frente a la cámara. | | `Black_and_White_Printed_Copy_Attack` | Detección de documentos impresos en papel en escala de grises o blanco y negro. | | `Photo_Replacement_Attack` | La región de datos parece genuina pero la región del retrato tiene una fotografía impresa encima. No detecta manipulaciones digitales. | | `SECURITY_PHOTO_CHECK` | La foto del retrato en el documento de identidad está manipulada. | | `SECURITY_DATA_CHECK` | Los datos del documento muestran alteraciones en su contenido. | | `SECURITY_OCR_CHECK` | La comparación de datos comunes entre el anverso y reverso del documento de identidad falla. | | `NOT_PROCESSED_OCR` | No se pudieron extraer los datos OCR del documento de identidad. | | `NOT_PROCESSED_PHOTO_CHECK` | No se pudo realizar la verificación de la foto del retrato del documento de identidad. | | `NOT_PROCESSED_DATA_CHECK` | No se pudo realizar la verificación de los valores de los campos del documento de identidad. | #### Ejemplo de respuesta — Validación exitosa ```json { "serviceTransactionId": "24f7451f-9bc2-483b-xxxx-a8421d98c664", "serviceResultCode": 0, "serviceResultLog": "Executed OK", "timestamp": "2022-12-15T16:00:00.000Z", "serviceResult": { "result": { "decision": "Credible", "IQA": { "FTA": "DOCUMENT_TOO_CLOSE" } }, "api_version": "pad_cards_v1_1_1", "processing_modules_time": "" }, "serviceDocumentData": "{\"CHECKS\":{\"BIRTH_DATE_SIDE_MATCH\":false,\"SEX_SIDE_MATCH\":true,\"SURNAME_SIDE_MATCH\":true,\"PERSONAL_NUMBER_SIDE_MATCH\":true,\"EXPIRATION_DATE_SIDE_MATCH\":true,\"NAME_SIDE_MATCH\":true,\"NATIONALITY_SIDE_MATCH\":true},\"SUBTYPE\":null,\"BACKSIDE\":{\"FIELD_DATA\":{\"ADDRESS\":[\"\",\"\"],\"CUIL\":\"\"},\"MRZ_DATA\":{\"NATIONALITY\":\"\",\"SERIAL_NUMBER\":\"\",\"SURNAME\":\"\",\"EXPIRATION_DATE\":\"\",\"SEX\":\"\",\"BIRTH_DATE\":\"\",\"ISSUING_COUNTRY\":\"\",\"IDENTITY_NUMBER\":\"\",\"PERSONAL_NUMBER\":\"\",\"NAME\":\"\"}},\"FRONTSIDE\":{\"FIELD_DATA\":{\"NATIONALITY\":\"\",\"SURNAME\":\"\",\"EXPIRATION_DATE\":\"\",\"BARCODES\":[],\"SEX\":\"\",\"BIRTH_DATE\":\"\",\"PERSONAL_NUMBER\":\"\",\"EXPEDITION_DATE\":\"\",\"EXEMPLAR\":\"\",\"NAME\":\"\"}},\"SCORING\":{\"FIELDS_TOTAL\":0,\"FIELDS_RETURNED\":0,\"OVERALL_RATING\":0},\"DOC_MODEL\":\"\"}", "serviceTime": "20784" } ``` #### Ejemplo de respuesta — Error ```json { "serviceTransactionId": "6b308748-9898-4833-a7d4-85ff8b5d518f", "serviceResultCode": -13, "serviceResultLog": "Service Exception", "timestamp": "2025-08-29T03:50:02Z", "serviceResult": { "result": { "IQA": null, "decision": "Error", "reason": "NOT_PROCESSED_OCR" }, "api_version": "", "processing_modules_time": "" }, "serviceTime": "4234" } ``` #### `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" } ```