Autenticação biométrica: avisos e códigos

A Autenticação biométrica combina uma verificação de prova de vida com uma correspondência facial 1:1 opcional em relação à face de referência resolvida na criação da sessão (a portrait_image fornecida ou a face guardada do utilizador consultada através de vendor_data). Cada passo emite os seus próprios avisos no payload de decisão V3. Esta página lista cada código, onde surge e como os limiares se traduzem num estado final da sessão.

Visão geral

Quando uma sessão de autenticação biométrica é executada, a Didit:

Captura uma selfie em direto através de 3D Action, Flash ou Prova de vida passiva (method: ACTIVE_3D, FLASHING ou PASSIVE).
Extrai a maior face da captura e calcula a pontuação da sua prova de vida.
Se o fluxo de verificação incluir Correspondência facial, compara a face capturada com a face de referência da sessão (portrait_image fornecida ou a face guardada do utilizador).
Regista o resultado de cada passo, juntamente com eventuais avisos, na decisão da sessão.

Os avisos mantêm a estrutura partilhada do objeto de aviso utilizada em toda a plataforma: feature, risk, additional_data, log_type, short_description, long_description e node_id.

Onde surgem os avisos

Chave da resposta de decisão	Tag de funcionalidade no aviso	Quando é acionado
`liveness_checks[].warnings[]`	`LIVENESS`	Pontuação de prova de vida, qualidade da face, luminância, múltiplas faces e verificações de lista de bloqueio / lista de permissões / faces duplicadas.
`face_matches[].warnings[]`	`FACEMATCH`	Correspondência facial em relação à face de referência da sessão (`portrait_image` fornecida ou a face guardada do utilizador).

Numa sessão típica de autenticação biométrica existe um elemento em cada array. Em fluxos com múltiplas instâncias, o node_id em cada aviso permite distinguir qual o passo que o gerou.

Condições de recusa automática

Os seguintes avisos recusam sempre o respetivo passo (log_type: "error"), independentemente de como configurou o fluxo:

Risco	Funcionalidade	Motivo da recusa automática
`FACE_IN_BLOCKLIST`	`LIVENESS`	A face correspondeu a uma entrada na sua lista de bloqueio de faces.
`NO_FACE_DETECTED`	`LIVENESS`	Nenhuma face foi localizada durante a captura de prova de vida, ou o utilizador esgotou as tentativas de captura.
`LIVENESS_FACE_ATTACK`	`LIVENESS`	Foi detetado um ataque de apresentação (máscara, reprodução em ecrã, spoofing do tipo deepfake).
`NO_REFERENCE_IMAGE`	`FACEMATCH`	Não estava disponível nenhuma imagem de referência para realizar a comparação. Quando este aviso é acionado, `LOW_FACE_MATCH_SIMILARITY` é suprimido.

Quando NO_FACE_DETECTED é acionado, LOW_LIVENESS_SCORE é suprimido (não existe qualquer face para pontuar).

Limiares e ações configuráveis

Estes avisos são pontuados e depois associados a um estado através de limiares e ações que define por fluxo:

Risco	Funcionalidade	Comportamento configurável
`LOW_LIVENESS_SCORE`	`LIVENESS`	Pontuação igual ou inferior ao limiar de revisão → `In Review`; igual ou inferior ao limiar de recusa → `Declined`.
`LOW_FACE_MATCH_SIMILARITY`	`FACEMATCH`	Pontuação igual ou inferior ao limiar de revisão (predefinição 70) → `In Review`; igual ou inferior ao limiar de recusa (predefinição 50) → `Declined`.
`LOW_FACE_QUALITY`	`LIVENESS`	Limiar de revisão (predefinição 15) → `In Review`; limiar de recusa (predefinição 0, ou seja, recusa desativada) → `Declined`. Apenas Prova de vida passiva.
`LOW_FACE_LUMINANCE`	`LIVENESS`	Abaixo do limiar mínimo de luminância (predefinição 20): Nenhuma ação / Revisão (predefinição) / Recusa. Apenas Prova de vida passiva.
`HIGH_FACE_LUMINANCE`	`LIVENESS`	Acima do limiar máximo de luminância (predefinição 80): Nenhuma ação / Revisão (predefinição) / Recusa. Apenas Prova de vida passiva.
`MULTIPLE_FACES_DETECTED`	`LIVENESS`	Nenhuma ação (predefinição) / Revisão / Recusa quando é capturada mais de uma face. Apenas Prova de vida passiva.
`DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE`	`LIVENESS`	Uma ação partilhada para faces duplicadas: Nenhuma ação (predefinição) / Revisão / Recusa para correspondências com faces aprovadas ou importadas de outros utilizadores.
`DUPLICATED_FACE_NAME_MISMATCH`	`LIVENESS`	Ação específica (`face_liveness_duplicated_face_name_mismatch_action`): Nenhuma ação / Revisão (predefinição) / Recusa. Emitido juntamente com `DUPLICATED_FACE` quando a identidade da sessão correspondente não coincide com o nome resolvido desta sessão — consulte Avisos de prova de vida.

POSSIBLE_FACE_IN_BLOCKLIST (LIVENESS) não é configurável — uma correspondência de menor confiança com a lista de bloqueio é sempre encaminhada para Revisão (log_type: "warning").

Novas tentativas de captura

As falhas causadas apenas por riscos corrigíveis de qualidade de captura (pontuação baixa, ausência de face, qualidade, luminância, múltiplas faces — e baixa similaridade na correspondência facial) entram num ciclo de repetição antes de o estado se tornar definitivo: o utilizador obtém até um total de face_liveness_max_attempts / face_match_max_attempts tentativas (predefinição: 3; configurável entre 2 e 5 por nó do fluxo). Quando o limite de tentativas é esgotado, aplica-se o estado calculado da última tentativa e LIVENESS_MAX_ATTEMPTS_EXCEEDED ou FACE_MATCH_MAX_ATTEMPTS_EXCEEDED é registado como information para o registar.

Avisos de prova de vida

A API devolve exatamente estas strings de short_description e long_description:

`risk`	`short_description`	`long_description`
`LOW_LIVENESS_SCORE`	Low liveness score	The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data.
`NO_FACE_DETECTED`	No Face Detected in liveness	The system couldn’t identify a face during the liveness check, which may be due to poor image quality, improper positioning, or technical issues.
`LIVENESS_FACE_ATTACK`	Liveness Face Attack	The system detected a potential attempt to bypass the liveness check.
`FACE_IN_BLOCKLIST`	Face in blocklist	The system identified a face in the blocklist, which means the face is not allowed to be verified.
`POSSIBLE_FACE_IN_BLOCKLIST`	Possible face in blocklist	The system identified a possible face in the blocklist, which means the face is not allowed to be verified.
`FACE_IN_ALLOWLIST`	Face in allowlist	The face matched the application’s face allowlist, so duplicate-face actions were skipped for this signal.
`POSSIBLE_FACE_IN_ALLOWLIST`	Possible face in allowlist	The face possibly matched the application’s face allowlist, so possible duplicate-face actions were skipped for this signal.
`DUPLICATED_FACE`	Duplicated face from other approved session	The system identified a duplicated face from another approved session, requiring further investigation.
`POSSIBLE_DUPLICATED_FACE`	Possible duplicated face from other approved session	The system identified a possible duplicate face from another approved session, requiring further investigation.
`DUPLICATED_FACE_NAME_MISMATCH`	Duplicated face under a different name	The same face was already approved on another session, but under a different name. The identity behind the duplicate does not match the identity declared on this session, which is a strong indicator of identity fraud.
`MULTIPLE_FACES_DETECTED` (Apenas passiva)	Multiple faces detected	Multiple faces were detected in the liveness image. The system uses the largest face for liveness verification and face comparison, but the presence of multiple faces may require additional review.
`LOW_FACE_QUALITY` (Apenas passiva)	Low face quality	The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts.
`LOW_FACE_LUMINANCE` (Apenas passiva)	Low face luminance	The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.
`HIGH_FACE_LUMINANCE` (Apenas passiva)	High face luminance	The facial image is too bright or overexposed, which may affect the accuracy of liveness detection. Reduced lighting or avoiding direct light is recommended.
`LIVENESS_MAX_ATTEMPTS_EXCEEDED`	Maximum liveness attempts exceeded	The maximum number of liveness capture attempts has been reached. The last attempt’s computed status (decline or review) has been applied.

Correspondências na lista de bloqueio, lista de permissões e duplicados incluem additional_data com a sessão correspondente (blocklisted_session_id / allowlisted_session_id / duplicated_session_id, o respetivo *_session_number e api_service). Apenas um desses seis códigos surge por relatório. DUPLICATED_FACE_NAME_MISMATCH é a exceção: é emitido em conjunto com DUPLICATED_FACE, nunca em sua substituição, quando a identidade da sessão correspondente não coincide com o nome resolvido desta sessão. O respetivo additional_data adiciona name_match_score aos mesmos campos da sessão duplicada. Um nome escrito num sistema de escrita diferente em cada lado não é considerado uma divergência quando os documentos de identificação de ambas as sessões partilham o mesmo estado emissor, um número de documento ou número de identificação pessoal exato e uma data de nascimento sem contradições. Consulte Avisos de prova de vida.

Avisos de correspondência facial

`risk`	`short_description`	`long_description`
`LOW_FACE_MATCH_SIMILARITY`	Low face match similarity	The facial features of the provided image don’t closely match the reference image, suggesting a potential identity mismatch.
`NO_REFERENCE_IMAGE`	No source image found for performing face match	A reference image for facial comparison is missing, preventing the system from completing the face matching process.
`FACE_MATCH_MAX_ATTEMPTS_EXCEEDED`	Maximum face match attempts exceeded	The maximum number of face match capture attempts has been reached. The last attempt’s computed status (decline or review) has been applied.

Exemplo — recusada por ataque facial

{
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Declined",
      "method": "ACTIVE_3D",
      "score": 12.40,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": null,
      "face_luminance": null,
      "warnings": [
        {
          "feature": "LIVENESS",
          "risk": "LIVENESS_FACE_ATTACK",
          "additional_data": null,
          "log_type": "error",
          "short_description": "Liveness Face Attack",
          "long_description": "The system detected a potential attempt to bypass the liveness check.",
          "node_id": "feature_liveness"
        }
      ]
    }
  ],
  "face_matches": null
}

Exemplo — em análise por baixa similaridade

{
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "In Review",
      "score": 58.70,
      "source_image_session_id": "11111111-2222-3333-4444-555555555555",
      "source_image": "https://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../target.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "LOW_FACE_MATCH_SIMILARITY",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face match similarity",
          "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
          "node_id": "feature_face_match"
        }
      ]
    }
  ]
}

A pontuação (58.70) situa-se entre o limiar de recusa (por defeito 50) e o limiar de revisão (por defeito 70), pelo que o aviso inclui log_type: "warning" e o estado da correspondência facial é In Review. Neste exemplo, o aviso disparou numa sessão cujo session_id é 11111111-2222-3333-4444-555555555555 — source_image_session_id inclui o próprio id da sessão porque a referência teve origem no retrato guardado no momento da criação da sessão.

Tipos de aviso

A cada risco é atribuído um tipo de aviso com base na configuração da sua aplicação. Os avisos dividem-se em três categorias de gravidade:

Conteúdo relacionado

Relatório de Autenticação Biométrica

Onde liveness_checks[] e face_matches[] surgem na decisão V3.

Avisos de prova de vida

Referência completa de avisos de prova de vida, incluindo correspondência de rostos duplicados.

Avisos de correspondência facial

Referência completa de avisos de correspondência facial para comparações 1:1.

Autenticação

Verificação

Monitorização

Plataforma

Autenticação biométrica: avisos e códigos

Visão geral

Onde surgem os avisos

Condições de recusa automática

Limiares e ações configuráveis

Novas tentativas de captura

Avisos de prova de vida

Avisos de correspondência facial

Exemplo — recusada por ataque facial

Exemplo — em análise por baixa similaridade

Tipos de aviso

Conteúdo relacionado

Relatório de Autenticação Biométrica

Avisos de prova de vida

Avisos de correspondência facial

​Visão geral

​Onde surgem os avisos

​Condições de recusa automática

​Limiares e ações configuráveis

​Novas tentativas de captura

​Avisos de prova de vida

​Avisos de correspondência facial

​Exemplo — recusada por ataque facial

​Exemplo — em análise por baixa similaridade

​Tipos de aviso

​Conteúdo relacionado

Relatório de Autenticação Biométrica

Avisos de prova de vida

Avisos de correspondência facial

Visão geral

Onde surgem os avisos

Condições de recusa automática

Limiares e ações configuráveis

Novas tentativas de captura

Avisos de prova de vida

Avisos de correspondência facial

Exemplo — recusada por ataque facial

Exemplo — em análise por baixa similaridade

Tipos de aviso

Conteúdo relacionado