> 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/docs.facephi-pt-br/api-rest/identity-api/identity-api-reference/onboarding/morphology/document-pad-diagnostic.md). # Diagnóstico PAD do documento Serviço que permite verificar se o suporte de um documento de identidade é **genuíno ou não** por meio da análise da sua imagem, com o objetivo de detectar **ataques de apresentação** direcionados ao roubo de identidade. O resultado da validação pode retornar os seguintes valores: * **Crível**: O documento é genuíno. * **Duvidoso**: Não é possível assegurar se o documento é genuíno. * **Spoof**: O documento parece não ser genuíno. * **Erro**: O processo de validação encontrou um erro. O resultado é fornecido no campo **`decision`** da resposta do serviço, junto com o campo **`reason`** que especifica a causa das validações insatisfatórias. ### Requisitos de imagem #### Requisitos mínimos * Imagens HD, resolução mínima: **720px** * Pixels que mostrem o fundo ao redor do documento de pelo menos **5% da sua largura** * Nível mínimo de compressão: **JPEG 70** * O texto do documento deve ser legível por um OCR #### Requisitos recomendados * Imagens FullHD, resolução mínima: **1080px** * Documento centralizado na imagem e que ocupe mais de **5% do documento** * Sem compressão, com formatos como **PNG** * Foto bem iluminada, sem desfoque nem reflexos de luz ### Endpoint ``` POST /verify/pad/diagnostic ``` ### Cabeçalhos | Nome | Tipo | Obrigatório | Descrição | | ------------- | ------ | ----------- | ------------------------------------------------------------- | | **x-api-key** | string | **Sim** | API Key de autorização de acesso. | | **family** | string | Não | Valor: **Onboarding**. Obrigatório com o serviço de tracking. | {% hint style="info" %} Todas as chamadas aos Endpoints para tracking com **Identity Platform** devem conter o header `family`. {% endhint %} ### Corpo da solicitação **Content-Type:** `application/json` #### Parâmetros | Parâmetro | Tipo | Obrigatório | Descrição | | ---------------------- | ------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `frontSideImage` | string | **Sim** | Imagem codificada em **Base64** do lado frontal do documento a validar. | | `backSideImage` | string | **Sim** | Imagem codificada em **Base64** do lado posterior do documento a validar. | | `face` | string | Não | Imagem codificada em **Base64** do rosto da pessoa a validar (opcional). | | `tokenized` | boolean | **Sim** | Define se as imagens são enviadas em **formato tokenizado** ou em formato plano. | | `countryCode` | string | **Sim** | Código **ISO Alpha-3** do país emissor do documento de identidade. | | `idType` | string | **Sim** | Tipo de documento a validar. Valores possíveis: `PASSPORT`, `ID_CARD`, `RESIDENCE_PERMIT`, `DRIVERS_LICENSE`, `DRIVING_LICENSE`, `VISA` | | `tracking` | object | Não | Objeto que representa as informações de tracking necessárias. | | `tracking.extraData` | string | Não | Token gerado pelo SDK Mobile/Web. Contém informações de tracking tokenizadas com a Plataforma. | | `tracking.operationId` | string | Não | Identificador de operação gerado pelo SDK Mobile/Web. | #### Exemplo de solicitação ```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" } } ``` ### Respostas #### `200` Sucesso #### Parâmetros de resposta | Parâmetro | Tipo | Descrição | | ---------------------- | ------- | ----------------------------------------------------------------------- | | `serviceTransactionId` | string | Identificador de transação associado à solicitação processada pela API. | | `serviceResultCode` | integer | Código que indica o **resultado geral** da execução do serviço. | | `serviceResultLog` | string | Campo descritivo do resultado da execução. | | `timestamp` | string | Marca de tempo (UTC) da resposta no formato **ISO 8601**. | | `serviceResult` | object | Objeto com o resultado da validação. Veja a tabela a seguir. | | `serviceDocumentData` | string | String JSON com os dados extraídos por OCR do documento de identidade. | | `serviceTime` | string | Tempo de processamento **(milissegundos)**. | #### Parâmetros de resposta — `serviceResult.result` | Parâmetro | Tipo | Nullable | Descrição | | ---------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `decision` | string | Não | Decisão da validação. Valores possíveis: `Crível`, `Duvidoso`, `Spoof`, `Erro`. Ver [Resultados da validação de diagnóstico PAD](#pad-diagnostic-validation-results). | | `reason` | string | Sim | Motivo da rejeição (presente quando a decisão não é Crível). Veja [Motivos de rejeição do diagnóstico PAD](#pad-diagnostic-rejection-reasons). | | `IQA` | object | Sim | Dados de avaliação da qualidade da imagem (Image Quality Assessment). | #### Parâmetros de resposta — `serviceResult` (adicionais) | Parâmetro | Tipo | Descrição | | ------------------------- | ------ | ----------------------------------------------- | | `api_version` | string | Versão da API utilizada para o processamento. | | `processing_modules_time` | string | Tempo de execução dos módulos de processamento. | #### Service Result Code O `serviceResultCode` indica o resultado geral da execução do serviço: | serviceResultCode | Descrição | Código HTTP | | ----------------- | -------------------------------------------------------------------------------------- | ----------- | | 0 | A execução do serviço foi bem-sucedida, o módulo processou a solicitação corretamente. | 200 | #### Resultados da validação de diagnóstico PAD O serviço de diagnóstico PAD (Presentation Attack Detection) retorna os resultados da validação no campo `decision`: | decision | Descrição | | ---------- | -------------------------------------------------- | | `Crível` | O documento é genuíno. | | `Duvidoso` | Não é possível assegurar se o documento é genuíno. | | `Spoof` | O documento parece não ser genuíno. | | `Erro` | O processo de validação encontrou um erro. | #### Motivos de rejeição do diagnóstico PAD Quando o resultado da validação não é satisfatório, o campo `reason` fornece detalhes específicos: | reason | Descrição | | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `Screen_Replay_Attack` | Um atacante apresenta uma imagem ou vídeo de um documento diante da câmera. | | `Black_and_White_Printed_Copy_Attack` | Detecção de documentos impressos em papel em escala de cinza ou preto e branco. | | `Photo_Replacement_Attack` | A região de dados parece genuína, mas a região do retrato tem uma fotografia impressa por cima. Não detecta manipulações digitais. | | `SECURITY_PHOTO_CHECK` | A foto do retrato no documento de identidade está manipulada. | | `SECURITY_DATA_CHECK` | Os dados do documento mostram alterações em seu conteúdo. | | `SECURITY_OCR_CHECK` | A comparação de dados comuns entre o anverso e o verso do documento de identidade falha. | | `NOT_PROCESSED_OCR` | Não foi possível extrair os dados OCR do documento de identidade. | | `NOT_PROCESSED_PHOTO_CHECK` | Não foi possível realizar a verificação da foto do retrato do documento de identidade. | | `NOT_PROCESSED_DATA_CHECK` | Não foi possível realizar a verificação dos valores dos campos do documento de identidade. | #### Exemplo de resposta — Validação bem-sucedida ```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" } ``` #### Exemplo de resposta — Erro ```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` Solicitação inválida ```json { "status": 400, "title": "Solicitação inválida", "detail": "Requisição inválida.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400", "errors": [] } ``` #### `401` Não autorizado ```json { "message": "Não autorizado" } ``` #### `403` Acesso negado ```json { "Message": "O usuário não está autorizado a acessar este recurso com uma negação explícita" } ``` #### `502` Gateway inválido ```json { "status": 502, "title": "Gateway inválido", "detail": "O servidor recebeu uma resposta inválida.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502" } ``` #### `504` Gateway Timeout ```json { "message": "A solicitação do Endpoint excedeu o tempo limite" } ```