Visão geral
A verificação de comprovante de endereço (POA) emite avisos empoa_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_riskse pela verificação de nome entre vários documentos. - API independente (
POST /v3/poa/): os avisos vêm apenas decheck_poa_risks. Não há ciclo de novas tentativas, nem contexto de documento de identidade verificado, e há apenas um documento, portantoNAME_MISMATCH_ID_VERIFICATION,POA_NAME_MISMATCH_BETWEEN_DOCUMENTS,POA_MAX_ATTEMPTS_EXCEEDEDeFUTURE_ISSUE_DATEnunca 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_DATEePOA_NAME_NOT_DETECTEDsão fixados em Recusar neste endpoint.POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATIONeUNPARSABLE_OR_INVALID_ADDRESSsã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_DOCUMENTSePOA_MAX_ATTEMPTS_EXCEEDEDnunca são gerados. Um documento com data futura não é recusado automaticamente neste endpoint.
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 deVerificationSettings):
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_documentmaisadditional_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 avisoNAME_MISMATCH*correspondente.
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
- Relatório de comprovante de endereço: 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: tipos de documento aceitos
- Modelos de dados: Comprovante de endereço: esquema canônico e objeto Warning
- Webhooks:
status.updatedinclui os avisos de POA