> 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/midapi-v2/document-services/document-validation/respuesta-de-resultado.md). # Resposta do resultado Quando a transação está no estado `COMPLETED`, a resposta de `GET /document/validate/{transactionId}` inclui o diagnóstico completo: #### Exemplo de resposta ```json { "transactionId": "1c7d...e9", "status": "COMPLETED", "diagnostic": "DECLINED", "rejectionReason": 160, "diagnostics": [ { "code": "160", "result": "fail", "reason": "Presentation attack detected", "category": "attack_detection" }, { "code": "500", "result": "pass", "reason": "Qualidade ruim da imagem frontal", "category": "integrity" }, { "code": "501", "result": "pass", "reason": "Qualidade ruim da imagem traseira", "category": "integrity" }, { "code": "502", "result": "pass", "reason": "Incompatibilidade de identidade entre o retrato e a imagem fantasma", "category": "biometric" }, { "code": "503", "result": "pass", "reason": "Incompatibilidade entre a idade estimada da selfie e do retrato", "category": "logical" }, { "code": "504", "result": "pass", "reason": "Incompatibilidade entre o sexo estimado da selfie e do retrato", "category": "logical" } ], "ocr": { "mrz": { "documentType": "ID", "issuingState": "NIC", "documentNumber": "6191000E", "nationality": "NIC", "dateOfBirth": "2003-02-14", "expiryDate": "2029-11-20", "sex": "M", "surname": "ROMERO LOPEZ", "givenNames": "ELVIN ANTONIO", "mrzValid": true }, "viz": { "documentClassification": ["NIC-00-IDC-2017-001-01-01"], "vizType": "VIZ_similar_to_ID_document" } }, "timestamp": "2026-06-26T12:00:05.000Z" } ``` {% hint style="info" %} Os campos opcionais (`diagnostic`, `rejectionReason`, `diagnostics`, `ocr`, `failureReason`) são omitidos da resposta quando não se aplicam, em vez de serem enviados com valor `null`. Por exemplo, um `diagnostic = APPROVED` nunca inclui `rejectionReason`. As linhas de `diagnostics[]` são resultados independentes para cada verificação (`result = pass` ou `fail`): pode haver linhas com `result = fail` mesmo quando o diagnóstico global é `APPROVED`, se essa verificação específica não foi determinante para o resultado final. Quando `status = FAILED`, a resposta inclui apenas `transactionId`, `status`, `failureReason` e `timestamp`. {% endhint %} ### Campos principais | Campo | Descrição | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `diagnostic` | `APPROVED` \| `DECLINED` \| `DOUBTFUL`. Só é incluído quando `status = COMPLETED`. `DOUBTFUL` só aparece na modalidade automática (ver [Modalidades do serviço](/docs.facephi-pt-br/api-rest/midapi-v2/document-services/document-validation.md#modalidades-del-servicio)). | | `rejectionReason` | Código de razão do catálogo do serviço, preenchido se `diagnostic = DECLINED` ou `diagnostic = DOUBTFUL`. | | `diagnostics[]` | Detalhe das validações individuais executadas (`code`, `result`, `reason`, `category`). | | `ocr.mrz` | Dados extraídos da zona de leitura mecânica (MRZ) do documento. | | `ocr.viz` | Classificação do documento a partir de sua zona visual (VIZ). | ### diagnostics | Campo | Tipo | Descrição | | ---------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `code` | string | Código de razão do catálogo do serviço. | | `result` | string | `pass` \| `fail`. Resultado dessa validação específica. | | `reason` | string | Descrição legível da validação. | | `category` | string | Agrupamento temático: `input`, `integrity`, `logical`, `biometric`, `attack_detection`, `unsupported`, `low_confidence`, `processing`, `block_list`, `escalated_review`, `unknown`. | ### Catálogo de códigos de razão (`rejectionReason` / `diagnostics[].code`) Convém distinguir dois níveis de leitura do resultado: * **Geral.** O campo `diagnostic` (`APPROVED` / `DECLINED` / `DOUBTFUL`) é o veredito global da transação, e `rejectionReason` é o **código geral** que resume o motivo quando `diagnostic = DECLINED` ou `diagnostic = DOUBTFUL`. * **Granular.** Cada linha de `diagnostics[]` é uma **sinal individual** (`code` + `result = pass|fail`), cujo `code` vem deste mesmo catálogo. Pode haver sinais `fail` mesmo com um diagnóstico `APPROVED`, e sinais que acompanham qualquer resultado (ver códigos 500-506). Esses códigos são estáveis. Recomenda-se tratá-los como catálogo fechado e consultar esta tabela para exibir mensagens ao usuário final. | code | reason | category | | ---- | --------------------------------------------------- | ----------------- | | 100 | Document front image missing | input | | 101 | Document back image missing | input | | 102 | Document front not detected | integrity | | 103 | Document back not detected | integrity | | 104 | Error loading front image | input | | 105 | Error loading back image | input | | 106 | Unsupported dimensions for front image | integrity | | 107 | Unsupported dimensions for back image | integrity | | 108 | Unsupported aspect ratio for front image | integrity | | 109 | Unsupported aspect ratio for back image | integrity | | 110 | Unsupported depth for front image | integrity | | 111 | Unsupported depth for back image | integrity | | 112 | Multiple documents detected on front image | attack\_detection | | 113 | Multiple documents detected on back image | attack\_detection | | 120 | Document annulled or damaged | integrity | | 130 | Document MRZ invalid hashes | logical | | 131 | Document expired | logical | | 132 | Document MRZ not detected | logical | | 133 | Document MRZ dates inconsistent | logical | | 134 | Document MRZ invalid format | logical | | 150 | Document photo missing | biometric | | 160 | Presentation attack detected | attack\_detection | | 161 | Manipulation attack detected | attack\_detection | | 170 | Selfie face not detected | integrity | | 171 | Identity mismatch between portrait and selfie image | biometric | | 200 | Face matched in global block list | block\_list | | 201 | Face matched in platform block list | block\_list | | 300 | Fast-Auto-Screening document version not supported | unsupported | | 310 | Fast-Auto-Screening country not supported | unsupported | | 311 | Potential presentation attack detected | attack\_detection | | 312 | Potential manipulation attack detected | attack\_detection | | 320 | Fast-Auto-Screening low confidence score | low\_confidence | | 330 | Timeout whilst waiting for the OCR service | processing | | 331 | Error calling OCR pipeline | processing | | 332 | Mismatch between VIZ and the MRZ fields | logical | | 340 | VIZ birthdate mismatch with MRZ | logical | | 341 | VIZ country mismatch with MRZ | logical | | 342 | VIZ document type mismatch with MRZ | logical | | 343 | VIZ document number mismatch with MRZ | logical | | 344 | VIZ expiry date mismatch with MRZ | logical | | 345 | VIZ given names mismatch with MRZ | logical | | 346 | VIZ nationality mismatch with MRZ | logical | | 347 | VIZ second optional data mismatch with MRZ | logical | | 348 | VIZ optional data mismatch with MRZ | logical | | 349 | VIZ sex mismatch with MRZ | logical | | 350 | VIZ surname mismatch with MRZ | logical | | 500 | Poor front image quality | integrity | | 501 | Poor back image quality | integrity | | 502 | Identity mismatch between portrait and ghost image | biometric | | 503 | Mismatch estimated age selfie vs portrait | logical | | 504 | Mismatch estimated sex selfie vs portrait | logical | | 505 | Mismatch estimated age portrait vs mrz | logical | | 506 | Mismatch estimated sex portrait vs mrz | logical | | 600 | Escalated validation declined | escalated\_review | | 601 | Escalated validation flagged for manual review | escalated\_review | | 602 | Escalated validation timed out | escalated\_review | | 603 | Escalated validation not completed | escalated\_review | | 999 | Validation declined | unknown | {% hint style="info" %} **Códigos 100-171 e 300-350** acompanham uma rejeição ou um resultado inconclusivo: entradas ausentes ou ilegíveis (`input`), problemas de integridade/qualidade do documento (`integrity`), inconsistências lógicas de MRZ e de contraste VIZ↔MRZ (`logical`), ataques de apresentação ou manipulação (`attack_detection`fast auto-screening *de versão/país e confiança (* ) e erros do próprio pipeline de OCR (`unsupported` / `low_confidence`) e erros do próprio pipeline de OCR (`processing`). **Códigos 200/201** indicam uma correspondência na lista de bloqueio de rostos, global ou da própria plataforma. **Códigos 500-506** são sinais de verificação informativos (qualidade de imagem e coincidências biométricas de idade/sexo entre selfie, retrato e MRZ): aparecem como linhas de `diagnostics[]` (`result = pass` ou `fail`) e podem acompanhar **qualquer** estado, inclusive `APPROVED`; não são usados como `rejectionReason` por si sós. **Códigos 600-603** correspondem a uma rejeição, revisão, expiração ou abandono durante uma verificação adicional escalonada quando a análise inicial não é conclusiva. Os códigos que acompanham uma análise **inconclusiva**, entre eles os do intervalo 300-350, são os que levará o `rejectionReason` de um `diagnostic = DOUBTFUL` na [modalidade automática](/docs.facephi-pt-br/api-rest/midapi-v2/document-services/document-validation.md#modalidades-del-servicio). Na modalidade híbrida esse mesmo caso é resolvido após a verificação adicional, e o motivo final é o que corresponder a essa resolução. {% endhint %} ### Rejeição por qualidade vs detecção de fraude Nem todos os `DECLINED` significam a mesma coisa. A `category` de cada código permite distinguir três situações e comunicar ao usuário final a mensagem adequada: * **Problema de captura ou qualidade** (categorias `input` e `integrity`): a imagem não é utilizável ou o documento não é detectado corretamente. **Não é uma acusação de fraude.** Inclui entradas ausentes/ilegíveis (100, 101, 104, 105) e problemas de integridade/qualidade (102, 103, 106-111, 120, 170, 500, 501). Ação típica: solicitar uma nova captura com melhor qualidade. * **Sinal de fraude ou ataque** (categorias `attack_detection` e `block_list`): rejeição genuína por indícios de fraude. Inclui múltiplos documentos ou ataques de apresentação/manipulação (112, 113, 160, 161), sua variante **potencial**, quando a análise detecta indícios sem chegar a confirmá-los (311, 312), e correspondências na lista de bloqueio de rostos (200, 201). * **Inconsistência de dados ou biometria** (categorias `logical` e `biometric`): os dados não são coerentes entre si, sem ser um problema puro de qualidade nem um ataque explícito. Inclui inconsistências de MRZ e de contraste VIZ↔MRZ (130-134, 332, 340-350) e comparações biométricas (171, 502-506). ### Dados OCR | Campo (`ocr.mrz`) | Descrição | | ------------------------ | ---------------------------------------------- | | `documentType` | Tipo de documento (por ex. `ID`, `PASSPORT`). | | `issuingState` | País emissor (código ISO). | | `documentNumber` | Número de documento. | | `nationality` | Nacionalidade do titular. | | `dateOfBirth` | Data de nascimento. | | `expiryDate` | Data de validade do documento. | | `sex` | Sexo registrado no documento. | | `surname` / `givenNames` | Sobrenomes e nomes. | | `mrzValid` | `true` se a MRZ é válida (checksums corretos). | | Campo (`ocr.viz`) | Descrição | | ------------------------ | -------------------------------------------------------------------- | | `documentClassification` | Identificador(es) de classificação do modelo de documento detectado. | | `vizType` | Tipo de zona visual reconhecida no documento. |