Pular para o conteúdo principal

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

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

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)

Documento expirado + endereço ausente (recusa automática)

Divergência de nome (Revisão por padrão)

Relacionados

Tipos de aviso

Última modificação em 1 de novembro de 2026