Saltar para o conteúdo principal

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

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

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)

Documento expirado + morada em falta (recusa automática)

Discrepância de nome (Revisão por predefinição)

Relacionados

Tipos de avisos

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