> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Comprovativo de morada: avisos e códigos de erro > Códigos de aviso de comprovativo de morada na Didit: divergência de nome, documentos expirados e configuração de recusa automática. ## Visão geral A verificação do comprovativo de morada (POA) emite avisos em `poa_verifications[].warnings[]` para cada problema de qualidade, autenticidade ou correspondência detetado durante a extração e a análise forense. Cada aviso é um [objeto Warning](https://docs.didit.me/pt/reference/data-models.md#objeto-de-aviso) com `feature` definido como `"PROOF_OF_ADDRESS"`. Um conjunto reduzido de riscos força sempre o estado `Declined`; os restantes seguem uma ação por risco (`DECLINE` / `REVIEW` / `NO_ACTION`) configurada no seu fluxo. Todos os riscos abaixo são verificados em relação ao pipeline de decisão de produção; as cadeias de carateres exatas de descrição curta e longa são reproduzidas textualmente nas tabelas. > [!NOTE] > > A extração de POA introduz uma latência de **5–15 segundos** por documento. Os avisos são registados apenas quando o passo do fluxo é concluído; não efetue pedidos repetidos (polling) com um intervalo inferior a 5 s. ## Dois caminhos de produção Os avisos de POA são gerados através de dois caminhos diferentes, e o conjunto de riscos difere entre eles: * **Sessões de fluxo** (o passo de POA dentro de uma sessão de verificação) — o endpoint de carregamento executa primeiro uma validação bloqueante com um ciclo de nova tentativa (consulte [Comportamento de nova tentativa](#comportamento-de-nova-tentativa-sessões-de-fluxo)); em seguida, os avisos finais armazenados são calculados por `check_poa_risks` em conjunto com a verificação de nome em múltiplos documentos. * **API independente** (`POST /v3/poa/`) — os avisos provêm unicamente de `check_poa_risks`. Não existe ciclo de nova tentativa, não há contexto de documento de identificação verificado e existe apenas um documento, pelo que `NAME_MISMATCH_ID_VERIFICATION`, `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS`, `POA_MAX_ATTEMPTS_EXCEEDED` e `FUTURE_ISSUE_DATE` **nunca** são gerados pela API independente. Os erros de validação pré-extração são descartados neste caminho. `POOR_DOCUMENT_QUALITY` está definido no enum de riscos e reservado no mapeamento de ações, mas **nenhum caminho de código no pipeline de POA o produz** — nunca surge em `warnings[]` em nenhum dos caminhos. Não crie ramificações lógicas com base nele. ## Avisos de recusa automática (forçam sempre `Declined`) Estes riscos constam de `AUTO_DECLINE_RISKS`; quando registados, o estado do POA é `Declined`, independentemente da configuração, e `log_type` é sempre `error`. | Risco | Causa | Resolução recomendada | | - | - | - | | `MISSING_ADDRESS_INFORMATION` | Não foi possível extrair qualquer morada do documento. | Peça ao utilizador para reenviar um documento que mostre claramente a sua morada. | | `POA_DOCUMENT_EXPIRED` | O documento está expirado por um de dois caminhos: a sua **data de validade impressa** já passou ou é **mais antigo do que a idade máxima configurada** para o seu tipo. Predefinições: **3 meses** para `UTILITY_BILL` e `BANK_STATEMENT`, **12 meses** para `GOVERNMENT_ISSUED_DOCUMENT` e `OTHER_POA_DOCUMENT` (um mês conta como 30 dias; `-1` desativa a verificação). `additional_data` contém sempre `expiration_reason` (`printed_expiration` ou `age_window`), `document_type`, `document_subtype` e `issue_date`; o caminho `printed_expiration` adiciona `expiration_date`, e o caminho `age_window` adiciona `max_age_months`. | Peça ao utilizador um documento válido ou mais recente, ou aumente `age_months` para esse tipo. | | `INVALID_DOCUMENT_TYPE` | O documento não pôde ser classificado em nenhum tipo de POA suportado (`document_type` recai em `UNKNOWN`). | Peça ao utilizador para reenviar; verifique se o ficheiro não está corrompido. | | `UNABLE_TO_VALIDATE_DOCUMENT_AGE` | A própria verificação da idade do documento falhou (erro ao calcular a caducidade a partir da data de emissão). | Peça ao utilizador um documento com uma data de emissão claramente legível. | `FUTURE_ISSUE_DATE` também está listado em `AUTO_DECLINE_RISKS`, mas tem um único emissor na validação pré-extração (uma data de emissão com mais de 7 dias no futuro) cujos erros apenas alimentam o **ciclo de nova tentativa do fluxo** — manifesta-se aí como um erro de carregamento bloqueante, nunca é gerado pela API independente e não é registado em `warnings[]`. Consulte [Comportamento de nova tentativa](#comportamento-de-nova-tentativa-sessões-de-fluxo). ## Avisos configuráveis Cada um destes avisos depende de uma opção de ação no nó POA do fluxo (`DECLINE` / `REVIEW` / `NO_ACTION`). O `log_type` do aviso corresponde à ação configurada: `error` para Recusar, `warning` para Revisão, `information` para Sem ação. | Risco | Causa | Opção de ação | Predefinição | | - | - | - | - | | `NAME_MISMATCH_WITH_PROVIDED` | O nome no documento obtém uma pontuação inferior a `poa_name_match_score_threshold` (predefinido 86) em relação ao nome indicado na criação da sessão (`expected_details`). | `poa_name_or_address_mismatch_action` | Revisão | | `NAME_MISMATCH_ID_VERIFICATION` | O nome no documento obtém uma pontuação inferior ao limiar em relação ao documento de identidade verificado. `additional_data`: `{ poa_name, kyc_name, match_score }`. Apenas em sessões de fluxo. | `poa_name_or_address_mismatch_action` | Revisão | | `ADDRESS_MISMATCH_WITH_PROVIDED` | A morada extraída difere da morada indicada através da API, ou uma das moradas não pôde ser verificada como morada residencial. | `poa_name_or_address_mismatch_action` | Revisão | | `POA_COUNTRY_MISMATCH_WITH_PROVIDED` | O país do documento não corresponde ao país indicado através da API (normalizado ISO-3). `additional_data`: `{ expected_country, extracted_country }`. | `poa_name_or_address_mismatch_action` | Revisão | | `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` | Dois ou mais documentos POA na mesma sessão apresentam nomes diferentes. `additional_data` inclui os IDs de ambos os nós, ambos os nomes e a pontuação de correspondência. Apenas em sessões de fluxo. | `poa_name_or_address_mismatch_action` | Revisão | | `DOCUMENT_METADATA_MISMATCH` | O ficheiro está vazio (`file_size` 0) ou as datas EXIF estão mal formadas. | `poa_document_issues_action` | Revisão | | `SUSPECTED_DOCUMENT_MANIPULATION` | A análise forense encontrou indícios de manipulação: modificação após assinatura digital (`is_tampered`), manipulação de texto sobreposto (com retângulos em `additional_data.manipulated_regions`), um editor de PDF conhecido, datas EXIF inconsistentes ou uma reexportação suspeita. `additional_data.detection_method` indica a verificação que foi acionada. | `poa_document_authenticity_action` | **Recusar** | | `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` | Um campo de texto foi apagado e reescrito noutro tipo de letra, e não é possível determinar, a partir do ficheiro, se o conteúdo foi alterado: os editores online também reescrevem texto que não foi modificado. Este aviso nunca dispara `SUSPECTED_DOCUMENT_MANIPULATION` por si só; se outro sinal o disparar no mesmo documento, decide a mais restritiva das duas ações. `additional_data.detection_method` é `unproven_text_replacement`, com `replaced_text` e `manipulated_regions`. Um ficheiro que não pôde ser analisado na totalidade também dispara este aviso, porque a parte não analisada pode conter esse campo: nesse caso, `detection_method` é `analysis_incomplete`, com `replaced_text` e `manipulated_regions` vazios, a menos que um campo tenha sido encontrado na parte analisada. | `poa_document_unproven_text_replacement_action` | Revisão | | `UNSUPPORTED_DOCUMENT_LANGUAGE` | O idioma do documento não consta de `poa_languages_allowed`. | `poa_unsupported_language_action` | **Recusar** | | `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | O tipo de documento detetado não está ativado em `poa_documents_allowed` para o país do documento, ou o seu subtipo está explicitamente desativado. | `poa_unsupported_document_type_action` | **Recusar** | | `ISSUER_NOT_IDENTIFIED` | Não foi possível identificar a instituição emissora a partir do documento. | `poa_issuer_not_identified_action` | Revisão | | `UNABLE_TO_EXTRACT_ISSUE_DATE` | Não foi possível localizar no documento uma data de emissão válida. | `poa_issue_date_not_detected_action` | Revisão | | `POA_NAME_NOT_DETECTED` | Não foi detetado nenhum nome no documento. | `poa_issue_date_not_detected_action` (opção partilhada) | Revisão | | `UNPARSABLE_OR_INVALID_ADDRESS` | Foi extraída uma morada, mas não foi possível analisá-la e geocodificá-la como morada residencial válida. | `poa_unparsable_or_invalid_address_action` | Revisão | | `POA_MAX_ATTEMPTS_EXCEEDED` | O utilizador esgotou `poa_max_retry_attempts` (predefinido 2) no ciclo de tentativas do fluxo. `additional_data`: `{ attempts }`. Apenas em sessões de fluxo. | `poa_max_attempts_exceeded_action` | **Recusar** | > [!NOTE] > > Existe **uma única ação partilhada** para todas as divergências de nome e de morada: `poa_name_or_address_mismatch_action` abrange os dois riscos de nome, os dois riscos de morada e a verificação cruzada de nomes entre documentos. Não é possível configurar separadamente o comportamento para divergências de nome e de morada. Na API autónoma, o mesmo grupo segue a opção de pedido `poa_address_mismatch_action` (a opção `poa_name_mismatch_action` é aceite, mas nunca é lida). ## Diferenças na API autónoma (`POST /v3/poa/`) O endpoint autónomo cria o mesmo mapeamento de risco para ação, mas com opções ao nível do pedido que apenas aceitam `DECLINE` ou `NO_ACTION` (todas com `DECLINE` por padrão): * `UNABLE_TO_EXTRACT_ISSUE_DATE` e `POA_NAME_NOT_DETECTED` estão **definidos estaticamente como Recusar** neste endpoint. * `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` e `UNPARSABLE_OR_INVALID_ADDRESS` são aqui **informativos** — as suas ações têm como padrão Nenhuma ação e não são configuráveis por pedido. * `FUTURE_ISSUE_DATE`, `POOR_DOCUMENT_QUALITY`, `NAME_MISMATCH_ID_VERIFICATION`, `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` e `POA_MAX_ATTEMPTS_EXCEEDED` nunca são gerados — um documento com data futura **não** é recusado automaticamente neste endpoint. Consulte a [referência da API POST /v3/poa/](https://docs.didit.me/pt/standalone-apis/proof-of-address.md) para conhecer as opções do pedido. ## Comportamento de nova tentativa (sessões de fluxo) Numa sessão de verificação, o passo de carregamento do comprovativo de morada executa uma validação bloqueadora antes de o documento ser aceite. Quando encontra um erro bloqueador — `INVALID_DOCUMENT_TYPE`, `UNABLE_TO_EXTRACT_ISSUE_DATE`, `FUTURE_ISSUE_DATE`, `POA_NAME_NOT_DETECTED`, `MISSING_ADDRESS_INFORMATION`, `POA_COUNTRY_MISMATCH_WITH_PROVIDED`, `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`, `UNSUPPORTED_DOCUMENT_LANGUAGE` ou `POA_DOCUMENT_EXPIRED` — o carregamento é rejeitado com `400` e o código de risco como mensagem, e o utilizador pode tentar novamente com um documento melhor. Para `POA_DOCUMENT_EXPIRED`, o corpo do `400` também inclui `expiration_reason` (`printed_expiration` ou `age_window`) para que a sua interface possa apresentar o motivo exato; no percurso de `age_window`, inclui adicionalmente `max_age_months`. No percurso de `printed_expiration`, `max_age_months` é omitido intencionalmente, porque o documento foi rejeitado devido à sua data de validade impressa e não devido a uma janela de antiguidade. Assim que o utilizador esgota as tentativas de `poa_max_retry_attempts` (predefinição 2, configurável entre 2 e 5), o envio é aceite mesmo assim: os avisos guardados são recalculados a partir do documento guardado, `POA_MAX_ATTEMPTS_EXCEEDED` é anexado e o estado é determinado a partir do conjunto completo de riscos. É por esta razão que `FUTURE_ISSUE_DATE` pode bloquear um carregamento mas nunca surge em `warnings[]`. ## Definições configuráveis O nó de comprovativo de morada do fluxo expõe estes controlos (correspondentes aos campos de `VerificationSettings`): | Definição | Controla | Predefinição | | - | - | - | | `poa_name_or_address_mismatch_action` | `NAME_MISMATCH_WITH_PROVIDED`, `NAME_MISMATCH_ID_VERIFICATION`, `ADDRESS_MISMATCH_WITH_PROVIDED`, `POA_COUNTRY_MISMATCH_WITH_PROVIDED`, `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` | Revisão | | `poa_document_issues_action` | `DOCUMENT_METADATA_MISMATCH` | Revisão | | `poa_document_authenticity_action` | `SUSPECTED_DOCUMENT_MANIPULATION` | Recusar | | `poa_document_unproven_text_replacement_action` | `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` | Revisão (um fluxo que nunca faz revisão utiliza o seu próprio `poa_document_authenticity_action` quando este for Recusar, caso contrário Nenhuma ação; a API autónoma segue o `poa_document_authenticity_action` do pedido) | | `poa_unsupported_language_action` | `UNSUPPORTED_DOCUMENT_LANGUAGE` | Recusar | | `poa_unsupported_document_type_action` | `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | Recusar | | `poa_issuer_not_identified_action` | `ISSUER_NOT_IDENTIFIED` | Revisão | | `poa_issue_date_not_detected_action` | `UNABLE_TO_EXTRACT_ISSUE_DATE`, `POA_NAME_NOT_DETECTED` | Revisão | | `poa_unparsable_or_invalid_address_action` | `UNPARSABLE_OR_INVALID_ADDRESS` | Revisão | | `poa_max_attempts_exceeded_action` | `POA_MAX_ATTEMPTS_EXCEEDED` | Recusar | | `poa_documents_allowed` | Tipos de documentos aceites por país, cada um com `enabled` e `age_months` (`-1` = ilimitado); sobreposições por subtipo através de `document_subtypes_config`. | Fatura de serviços públicos e extrato bancário: 3 meses; emitido pelo governo e outros: 12 meses | | `poa_languages_allowed` | Idiomas de documentos aceites. | Todos os idiomas suportados | | `poa_name_match_score_threshold` | Pontuação mínima de correspondência de nomes (0–100) antes de os riscos `NAME_MISMATCH*` serem acionados. | 86 | | `poa_max_retry_attempts` | Tentativas de carregamento antes de o ciclo de repetição desistir (2–5). | 2 | ## Lógica de correspondência de nomes A correspondência de nomes do comprovativo de morada tolera variações comuns: * **Nomes do meio e iniciais** são correspondidos de forma tolerante (a presença/ausência é permitida). * **Nomes candidatos** — todos os nomes detetados no documento (`name_on_document` mais `additional_names`) recebem uma pontuação, mantendo-se o candidato com melhor pontuação. * **Limiar de correspondência** — a predefinição de `poa_name_match_score_threshold` é **86**; uma pontuação inferior aciona o aviso `NAME_MISMATCH*` correspondente. As pontuações numéricas são apresentadas no relatório como `name_match_score_expected_details` e `name_match_score_id_verification` (0–100). Os valores da pontuação são úteis para uma revisão detalhada, mesmo quando nenhum aviso foi gerado. ## Exemplos ### Manipulação por sobreposição (Recusar por predefinição) ```json theme={null} { "warnings": [ { "feature": "PROOF_OF_ADDRESS", "risk": "SUSPECTED_DOCUMENT_MANIPULATION", "additional_data": { "reason": "Overlay-text manipulation detected: same base font embedded with multiple subset prefixes on 1 page(s).", "detection_method": "overlay_text_manipulation", "signals": ["duplicate_font_subset", "glyph_fragmentation"], "duplicate_font_subsets": [{ "page": 1, "base_font": "Helvetica" }], "fragmented_fonts": [], "manipulated_regions": [ { "page": 1, "x": 102.4, "y": 318.1, "width": 187.0, "height": 18.0, "page_width": 595, "page_height": 842 } ] }, "log_type": "error", "short_description": "Suspected document manipulation", "long_description": "The system detected signs of potential document manipulation or editing.", "node_id": "feature_poa_1" } ] } ``` ### Documento expirado + morada em falta (recusa automática) ```json theme={null} { "warnings": [ { "feature": "PROOF_OF_ADDRESS", "risk": "POA_DOCUMENT_EXPIRED", "additional_data": { "expiration_reason": "age_window", "max_age_months": 3, "document_subtype": "ELECTRICITY_BILL", "document_type": "UTILITY_BILL", "issue_date": "2025-11-02" }, "log_type": "error", "short_description": "Document expired", "long_description": "The submitted document is older than the maximum accepted age of 3 months from its issue date, which exceeds the acceptable time period for validity.", "node_id": "feature_poa_1" }, { "feature": "PROOF_OF_ADDRESS", "risk": "MISSING_ADDRESS_INFORMATION", "additional_data": null, "log_type": "error", "short_description": "Missing address information", "long_description": "The document does not contain complete or clear address information that can be extracted.", "node_id": "feature_poa_1" } ] } ``` ### Discrepância de nome (Revisão por predefinição) ```json theme={null} { "warnings": [ { "feature": "PROOF_OF_ADDRESS", "risk": "NAME_MISMATCH_ID_VERIFICATION", "additional_data": { "poa_name": "JOHN B SMYTH", "kyc_name": "John A. Smith", "match_score": 60 }, "log_type": "warning", "short_description": "Name mismatch with ID verification", "long_description": "The full name on the document does not match the name from the user's verified identity documents.", "node_id": "feature_poa_1" } ] } ``` ## Relacionados * [Relatório de comprovativo de morada](https://docs.didit.me/pt/core-technology/proof-of-address/report-proof-of-address.md) — formato completo da resposta, análise forense de manipulação por sobreposição, semântica de estados * [Visão geral do comprovativo de morada](https://docs.didit.me/pt/core-technology/proof-of-address/overview.md) — tipos de documentos aceites * [Modelos de dados — Comprovativo de morada](https://docs.didit.me/pt/reference/data-models.md#comprovativo-de-morada) — esquema canónico e objeto Warning * [Webhooks](https://docs.didit.me/pt/integration/webhooks.md) — `status.updated` transporta avisos de comprovativo de morada ### Tipos de avisos This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.