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

{
  "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"
}

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.

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).
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

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_detectionfast 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. 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.

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.