Visão geral
A verificação do comprovativo de morada (POA) emite avisos empoa_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_risksem conjunto com a verificação de nome em múltiplos documentos. - API independente (
POST /v3/poa/) — os avisos provêm unicamente decheck_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 queNAME_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 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_DATEePOA_NAME_NOT_DETECTEDestão definidos estaticamente como Recusar neste endpoint.POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATIONeUNPARSABLE_OR_INVALID_ADDRESSsã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_DOCUMENTSePOA_MAX_ATTEMPTS_EXCEEDEDnunca são gerados — um documento com data futura não é recusado automaticamente neste endpoint.
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 deVerificationSettings):
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_documentmaisadditional_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 avisoNAME_MISMATCH*correspondente.
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
- Relatório de comprovativo de morada — formato completo da resposta, análise forense de manipulação por sobreposição, semântica de estados
- Visão geral do comprovativo de morada — tipos de documentos aceites
- Modelos de dados — Comprovativo de morada — esquema canónico e objeto Warning
- Webhooks —
status.updatedtransporta avisos de comprovativo de morada