> ## 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. # Avisos e códigos de erro do comprovante de endereço > Avisos de comprovante de endereço da Didit: nome divergente, documento expirado, metadados, tipos não suportados e recusa automática. ## Visão geral A verificação de comprovante de endereço (POA) emite avisos em `poa_verifications[].warnings[]` para cada problema de qualidade, autenticidade ou correspondência detectado durante a extração e a análise forense. Cada aviso é um [objeto Warning](https://docs.didit.me/pt-br/reference/data-models.md#objeto-de-aviso) com `feature` definido como `"PROOF_OF_ADDRESS"`. Alguns poucos riscos sempre forçam `Declined`; os demais seguem uma ação por risco (`DECLINE` / `REVIEW` / `NO_ACTION`) configurada no seu fluxo de verificação (workflow). Cada risco abaixo é verificado com base no pipeline de decisão em produção; as strings exatas das descrições curta e longa são reproduzidas literalmente nas tabelas. > [!NOTE] > > A extração de POA adiciona uma latência de **5 a 15 segundos** por documento. Os avisos só são gravados quando a etapa do fluxo é concluída; não faça polling com intervalo menor que 5 s. ## Dois fluxos de processamento Os avisos de POA são gerados em dois fluxos diferentes, e o conjunto de riscos difere entre eles: * **Sessões de workflow** (a etapa de POA dentro de uma sessão de verificação): o endpoint de upload primeiro executa uma validação bloqueante com um ciclo de novas tentativas (veja [Comportamento de novas tentativas](#comportamento-de-novas-tentativas-sessões-de-fluxo)) e, em seguida, os avisos finais armazenados são calculados por `check_poa_risks` e pela verificação de nome entre vários documentos. * **API independente** (`POST /v3/poa/`): os avisos vêm apenas de `check_poa_risks`. Não há ciclo de novas tentativas, nem contexto de documento de identidade verificado, e há apenas um documento, portanto `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 anteriores à extração são descartados nesse 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 gera**: ele nunca aparece em `warnings[]` em nenhum dos dois caminhos. Não crie lógica condicional com base nele. ## Avisos de recusa automática (sempre forçam `Declined`) Esses riscos estão em `AUTO_DECLINE_RISKS`; quando registrados, o status do POA é `Declined` independentemente da configuração, e `log_type` é sempre `error`. | Risco | Causa | Correção recomendada | | - | - | - | | `MISSING_ADDRESS_INFORMATION` | Não foi possível extrair nenhum endereço do documento. | Peça ao usuário que reenvie um documento que mostre claramente o endereço dele. | | `POA_DOCUMENT_EXPIRED` | O documento está expirado por uma de duas formas: a **data de validade impressa** já passou, ou ele é **mais antigo que a idade máxima configurada** para o seu tipo. Padrõ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` sempre inclui `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 usuário um documento válido ou mais recente, ou aumente `age_months` para esse tipo. | | `INVALID_DOCUMENT_TYPE` | Não foi possível classificar o documento em nenhum tipo de POA suportado (`document_type` passa a ser `UNKNOWN`). | Peça ao usuário que reenvie; verifique se o arquivo não está corrompido. | | `UNABLE_TO_VALIDATE_DOCUMENT_AGE` | A própria verificação da idade do documento falhou (erro ao calcular a validade a partir da data de emissão). | Peça ao usuário um documento com a data de emissão claramente legível. | `FUTURE_ISSUE_DATE` também está listado em `AUTO_DECLINE_RISKS`, mas tem uma única origem na validação anterior à extração (uma data de emissão mais de 7 dias no futuro), cujos erros alimentam apenas o **ciclo de novas tentativas do fluxo**: ele aparece ali como um erro de upload bloqueante, nunca é gerado pela API independente e não é gravado em `warnings[]`. Veja [Comportamento de novas tentativas](#comportamento-de-novas-tentativas-sessões-de-fluxo). ## Avisos configuráveis Cada um destes avisos segue um controle de ação no nó de POA do fluxo (`DECLINE` / `REVIEW` / `NO_ACTION`). O `log_type` do aviso reflete a ação configurada: `error` para Recusar, `warning` para Revisar e `information` para Nenhuma ação. | Risco | Causa | Controle de ação | Padrão | | - | - | - | - | | `NAME_MISMATCH_WITH_PROVIDED` | O nome no documento tem pontuação abaixo de `poa_name_match_score_threshold` (padrão 86) em relação ao nome informado na criação da sessão (`expected_details`). | `poa_name_or_address_mismatch_action` | Revisar | | `NAME_MISMATCH_ID_VERIFICATION` | O nome no documento tem pontuação abaixo do limiar em relação ao documento de identidade verificado. `additional_data`: `{ poa_name, kyc_name, match_score }`. Somente em sessões de fluxo. | `poa_name_or_address_mismatch_action` | Revisar | | `ADDRESS_MISMATCH_WITH_PROVIDED` | O endereço extraído é diferente do endereço informado via API, ou não foi possível confirmar que um dos endereços é residencial. | `poa_name_or_address_mismatch_action` | Revisar | | `POA_COUNTRY_MISMATCH_WITH_PROVIDED` | O país do documento não corresponde ao país informado via API (normalizado em ISO-3). `additional_data`: `{ expected_country, extracted_country }`. | `poa_name_or_address_mismatch_action` | Revisar | | `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` | Dois ou mais documentos de POA na mesma sessão trazem nomes diferentes. `additional_data` inclui os IDs dos dois nós, os dois nomes e a pontuação de correspondência. Somente em sessões de fluxo. | `poa_name_or_address_mismatch_action` | Revisar | | `DOCUMENT_METADATA_MISMATCH` | O arquivo está vazio (`file_size` 0) ou suas datas EXIF estão malformadas. | `poa_document_issues_action` | Revisar | | `SUSPECTED_DOCUMENT_MANIPULATION` | A análise forense encontrou indícios de manipulação: modificação após a assinatura digital (`is_tampered`), manipulação por sobreposição de texto (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** | | `UNSUPPORTED_DOCUMENT_LANGUAGE` | O idioma do documento não está em `poa_languages_allowed`. | `poa_unsupported_language_action` | **Recusar** | | `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | O tipo de documento detectado não está habilitado em `poa_documents_allowed` para o país do documento, ou seu subtipo está explicitamente desabilitado. | `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` | Revisar | | `UNABLE_TO_EXTRACT_ISSUE_DATE` | Não foi possível localizar uma data de emissão válida no documento. | `poa_issue_date_not_detected_action` | Revisar | | `POA_NAME_NOT_DETECTED` | Nenhum nome foi detectado no documento. | `poa_issue_date_not_detected_action` (controle compartilhado) | Revisar | | `UNPARSABLE_OR_INVALID_ADDRESS` | Um endereço foi extraído, mas não foi possível interpretá-lo e geocodificá-lo como um endereço residencial válido. | `poa_unparsable_or_invalid_address_action` | Revisar | | `POA_MAX_ATTEMPTS_EXCEEDED` | O usuário esgotou `poa_max_retry_attempts` (padrão 2) no ciclo de novas tentativas do fluxo. `additional_data`: `{ attempts }`. Somente em sessões de fluxo. | `poa_max_attempts_exceeded_action` | **Recusar** | > [!NOTE] > > Existe **uma única ação compartilhada** para todas as divergências de nome e endereço: `poa_name_or_address_mismatch_action` abrange os dois riscos de nome, os dois riscos de endereço e a verificação de nome entre documentos. Não é possível configurar separadamente o comportamento para divergências de nome e de endereço. Na API autônoma, o mesmo grupo segue a opção de requisição `poa_address_mismatch_action` (a opção `poa_name_mismatch_action` é aceita, mas nunca é lida). ## Diferenças da API autônoma (`POST /v3/poa/`) O endpoint autônomo monta o mesmo mapeamento de risco para ação, mas com opções no nível da requisição que aceitam apenas `DECLINE` ou `NO_ACTION` (todas com `DECLINE` como padrão): * `UNABLE_TO_EXTRACT_ISSUE_DATE` e `POA_NAME_NOT_DETECTED` são **fixados em Recusar** neste endpoint. * `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` e `UNPARSABLE_OR_INVALID_ADDRESS` são **informativos** aqui: suas ações têm Nenhuma ação como padrão e não podem ser configuradas por requisição. * `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-br/standalone-apis/proof-of-address.md) para ver as opções de requisição. ## Comportamento de novas tentativas (sessões de fluxo) Em uma sessão de verificação, a etapa de envio do POA executa uma validação bloqueante antes de aceitar o documento. Quando encontra um erro bloqueante (`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 envio é rejeitado com `400` e o código de risco como mensagem, e o usuário 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 sua interface possa mostrar o motivo exato; no caminho `age_window`, ele inclui ainda `max_age_months`. No caso de `printed_expiration`, `max_age_months` é omitido de propósito, porque o documento foi rejeitado pela data de validade impressa, e não por exceder a idade máxima permitida. Depois que o usuário esgota as `poa_max_retry_attempts` tentativas (padrão 2, configurável de 2 a 5), o envio é aceito mesmo assim: os avisos armazenados são recalculados a partir do documento salvo, `POA_MAX_ATTEMPTS_EXCEEDED` é adicionado e o status é definido com base no conjunto completo de riscos. É por isso que `FUTURE_ISSUE_DATE` pode bloquear um envio e, ainda assim, nunca aparecer em `warnings[]`. ## Configurações ajustáveis O nó de POA do fluxo expõe estes controles (correspondentes aos campos de `VerificationSettings`): | Configuração | Controla | Padrã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` | Recusa | | `poa_unsupported_language_action` | `UNSUPPORTED_DOCUMENT_LANGUAGE` | Recusa | | `poa_unsupported_document_type_action` | `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | Recusa | | `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` | Recusa | | `poa_documents_allowed` | Tipos de documento aceitos por país, cada um com `enabled` e `age_months` (`-1` = ilimitado); substituições por subtipo via `document_subtypes_config`. | Conta de consumo e extrato bancário: 3 meses; emitidos pelo governo e outros: 12 meses | | `poa_languages_allowed` | Idiomas de documento aceitos. | Todos os idiomas suportados | | `poa_name_match_score_threshold` | Pontuação mínima de correspondência de nome (0–100) abaixo da qual os riscos `NAME_MISMATCH*` são disparados. | 86 | | `poa_max_retry_attempts` | Tentativas de envio antes de o ciclo de novas tentativas ser encerrado (2–5). | 2 | ## Lógica de correspondência de nomes A correspondência de nomes do POA tolera variações comuns: * **Nomes do meio e iniciais** são comparados de forma flexível (presença ou ausência é permitida). * **Nomes candidatos**: cada nome detectado no documento (`name_on_document` mais `additional_names`) recebe uma pontuação, e o candidato com a melhor pontuação é mantido. * **Limiar de correspondência**: o valor padrão de `poa_name_match_score_threshold` é **86**; uma pontuação abaixo dele dispara o aviso `NAME_MISMATCH*` correspondente. As pontuações numéricas são expostas no relatório como `name_match_score_expected_details` e `name_match_score_id_verification` (0–100). Os valores de pontuação são úteis para uma revisão detalhada mesmo quando nenhum aviso foi gerado. ## Exemplos ### Manipulação de sobreposição (Recusa por padrã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 + endereço ausente (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" } ] } ``` ### Divergência de nome (Revisão por padrã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 comprovante de endereço](https://docs.didit.me/pt-br/core-technology/proof-of-address/report-proof-of-address.md): estrutura completa da resposta, análise forense de manipulação por sobreposição, semântica dos status * [Visão geral do comprovante de endereço](https://docs.didit.me/pt-br/core-technology/proof-of-address/overview.md): tipos de documento aceitos * [Modelos de dados: Comprovante de endereço](https://docs.didit.me/pt-br/reference/data-models.md#comprovante-de-endereço): esquema canônico e objeto Warning * [Webhooks](https://docs.didit.me/pt-br/integration/webhooks.md): `status.updated` inclui os avisos de POA ### Tipos de aviso This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.