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 contra a face de referência determinada na criação da sessão (a portrait_image fornecida ou a face armazenada do usuário, localizada por vendor_data). Cada etapa emite seus próprios avisos no payload de decisão V3. Esta página lista cada código, onde ele aparece e como os limiares se traduzem no status final da sessão.

Visão geral

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

Captura uma selfie ao vivo usando prova de vida por ação 3D, Flash ou passiva (method: ACTIVE_3D, FLASHING ou PASSIVE).
Extrai a maior face da captura e calcula a pontuação de prova de vida.
Se o fluxo de verificação (workflow) incluir Correspondência facial, compara a face capturada com a face de referência da sessão (a portrait_image fornecida ou a face armazenada do usuário).
Registra o resultado de cada etapa, junto com eventuais avisos, na decisão da sessão.

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

Onde os avisos aparecem

Chave da resposta de decisão	Tag de recurso no aviso	Quando é disparado
`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ão / face duplicada.
`face_matches[].warnings[]`	`FACEMATCH`	Correspondência facial com a face de referência da sessão (a `portrait_image` fornecida ou a face armazenada do usuário).

Em uma sessão típica de autenticação biométrica, há um item em cada array. Em fluxos com várias instâncias, o node_id de cada aviso identifica qual etapa o gerou.

Condições de recusa automática

Os avisos a seguir sempre recusam a etapa correspondente (log_type: "error"), independentemente de como você configurou o fluxo:

Risco	Recurso	Por que recusa automaticamente
`FACE_IN_BLOCKLIST`	`LIVENESS`	A face correspondeu a uma entrada da sua lista de bloqueio de faces.
`NO_FACE_DETECTED`	`LIVENESS`	Nenhuma face foi localizada durante a captura de prova de vida, ou o usuário esgotou as tentativas de captura.
`LIVENESS_FACE_ATTACK`	`LIVENESS`	Foi detectado um ataque de apresentação (máscara, reprodução em tela, spoofing do tipo deepfake).
`NO_REFERENCE_IMAGE`	`FACEMATCH`	Nenhuma imagem de referência estava disponível para realizar a comparação. Quando este aviso é disparado, `LOW_FACE_MATCH_SIMILARITY` é suprimido.

Quando NO_FACE_DETECTED é disparado, LOW_LIVENESS_SCORE é suprimido (não há face para pontuar).

Limiares e ações configuráveis

Estes avisos recebem uma pontuação e depois são mapeados para um status por meio dos limiares e ações que você define em cada fluxo:

Risco	Recurso	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 (padrão 70) → `In Review`; igual ou inferior ao limiar de recusa (padrão 50) → `Declined`.
`LOW_FACE_QUALITY`	`LIVENESS`	Limiar de revisão (padrão 15) → `In Review`; limiar de recusa (padrão 0, ou seja, recusa desativada) → `Declined`. Somente prova de vida passiva.
`LOW_FACE_LUMINANCE`	`LIVENESS`	Abaixo do limiar mínimo de luminância (padrão 20): Nenhuma ação / Revisão (padrão) / Recusa. Somente prova de vida passiva.
`HIGH_FACE_LUMINANCE`	`LIVENESS`	Acima do limiar máximo de luminância (padrão 80): Nenhuma ação / Revisão (padrão) / Recusa. Somente prova de vida passiva.
`MULTIPLE_FACES_DETECTED`	`LIVENESS`	Nenhuma ação (padrão) / Revisão / Recusa quando mais de uma face é capturada. Somente prova de vida passiva.
`DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE`	`LIVENESS`	Uma única ação compartilhada para face duplicada: Nenhuma ação (padrão) / Revisão / Recusa para correspondências com faces aprovadas ou importadas de outros usuários.
`DUPLICATED_FACE_NAME_MISMATCH`	`LIVENESS`	Ação própria (`face_liveness_duplicated_face_name_mismatch_action`): Nenhuma ação / Revisão (padrão) / Recusa. Emitido junto com `DUPLICATED_FACE` quando a identidade da sessão correspondente não coincide com o nome resolvido nesta 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

Falhas causadas apenas por riscos corrigíveis de qualidade da captura (pontuação baixa, nenhuma face, qualidade, luminância, múltiplas faces e, na correspondência facial, baixa similaridade) entram em um ciclo de novas tentativas antes de o status se tornar definitivo: o usuário tem até face_liveness_max_attempts / face_match_max_attempts tentativas no total (padrão 3, configurável de 2 a 5 por nó do fluxo). Quando o limite se esgota, aplica-se o status calculado na última tentativa, e LIVENESS_MAX_ATTEMPTS_EXCEEDED ou FACE_MATCH_MAX_ATTEMPTS_EXCEEDED é registrado como information para documentar o ocorrido.

Avisos de prova de vida

A API retorna exatamente estas strings de short_description e long_description:

`risk`	`short_description`	`long_description`
`LOW_LIVENESS_SCORE`	Pontuação de prova de vida baixa	A verificação de prova de vida resultou em uma pontuação baixa, o que indica possível uso de representações faciais não vivas ou dados biométricos de baixa qualidade.
`NO_FACE_DETECTED`	Nenhum rosto detectado na prova de vida	O sistema não conseguiu identificar um rosto durante a verificação de prova de vida, o que pode ocorrer por baixa qualidade da imagem, posicionamento inadequado ou problemas técnicos.
`LIVENESS_FACE_ATTACK`	Ataque facial na prova de vida	O sistema detectou uma possível tentativa de burlar a verificação de prova de vida.
`FACE_IN_BLOCKLIST`	Rosto na lista de bloqueio	O sistema identificou um rosto na lista de bloqueio, o que significa que esse rosto não pode ser verificado.
`POSSIBLE_FACE_IN_BLOCKLIST`	Possível rosto na lista de bloqueio	O sistema identificou um possível rosto na lista de bloqueio, o que significa que esse rosto não pode ser verificado.
`FACE_IN_ALLOWLIST`	Rosto na lista de permissões	O rosto correspondeu à lista de permissões de rostos da aplicação, por isso as ações de rosto duplicado foram ignoradas para este sinal.
`POSSIBLE_FACE_IN_ALLOWLIST`	Possível rosto na lista de permissões	O rosto possivelmente correspondeu à lista de permissões de rostos da aplicação, por isso as ações de possível rosto duplicado foram ignoradas para este sinal.
`DUPLICATED_FACE`	Rosto duplicado de outra sessão aprovada	O sistema identificou um rosto duplicado de outra sessão aprovada, o que exige investigação adicional.
`POSSIBLE_DUPLICATED_FACE`	Possível rosto duplicado de outra sessão aprovada	O sistema identificou um possível rosto duplicado de outra sessão aprovada, o que exige investigação adicional.
`DUPLICATED_FACE_NAME_MISMATCH`	Rosto duplicado com outro nome	O mesmo rosto já foi aprovado em outra sessão, mas com outro nome. A identidade por trás da duplicata não corresponde à identidade declarada nesta sessão, o que é um forte indicador de fraude de identidade.
`MULTIPLE_FACES_DETECTED` (somente no modo passivo)	Vários rostos detectados	Foram detectados vários rostos na imagem de prova de vida. O sistema usa o maior rosto para a verificação de prova de vida e a comparação facial, mas a presença de vários rostos pode exigir revisão adicional.
`LOW_FACE_QUALITY` (somente no modo passivo)	Baixa qualidade do rosto	A qualidade da imagem facial está abaixo do limiar aceitável, o que pode afetar a confiabilidade da detecção de prova de vida. Isso pode ser causado pela resolução da câmera, pelo foco ou por artefatos de compressão.
`LOW_FACE_LUMINANCE` (somente no modo passivo)	Baixa luminosidade do rosto	A imagem facial está escura demais, o que pode afetar a precisão da detecção de prova de vida. Recomenda-se melhorar as condições de iluminação.
`HIGH_FACE_LUMINANCE` (somente no modo passivo)	Alta luminosidade do rosto	A imagem facial está clara demais ou superexposta, o que pode afetar a precisão da detecção de prova de vida. Recomenda-se reduzir a iluminação ou evitar luz direta.
`LIVENESS_MAX_ATTEMPTS_EXCEEDED`	Número máximo de tentativas de prova de vida excedido	Foi atingido o número máximo de tentativas de captura de prova de vida. O status calculado na última tentativa (recusa ou revisão) foi aplicado.

As correspondências com a lista de bloqueio, a lista de permissões e rostos duplicados trazem additional_data com a sessão correspondente (blocklisted_session_id / allowlisted_session_id / duplicated_session_id, o *_session_number correspondente e api_service). Apenas um desses seis códigos aparece por relatório. DUPLICATED_FACE_NAME_MISMATCH é a exceção: ele é emitido além de DUPLICATED_FACE, nunca no lugar dele, quando a identidade da sessão correspondente não corresponde ao nome resolvido desta sessão. O additional_data dele acrescenta name_match_score aos mesmos campos da sessão duplicada. Um nome escrito em um sistema de escrita diferente em cada lado não é tratado como divergência quando os documentos de identidade das duas sessões têm o mesmo estado emissor, o mesmo número de documento ou número pessoal exato e uma data de nascimento não contraditória. Veja Avisos de prova de vida.

Avisos de correspondência facial

`risk`	`short_description`	`long_description`
`LOW_FACE_MATCH_SIMILARITY`	Baixa similaridade na correspondência facial	As características faciais da imagem fornecida não correspondem de perto à imagem de referência, o que sugere uma possível divergência de identidade.
`NO_REFERENCE_IMAGE`	Nenhuma imagem de origem encontrada para realizar a correspondência facial	Falta uma imagem de referência para a comparação facial, o que impede o sistema de concluir o processo de correspondência facial.
`FACE_MATCH_MAX_ATTEMPTS_EXCEEDED`	Número máximo de tentativas de correspondência facial excedido	Foi atingido o número máximo de tentativas de captura para a correspondência facial. O status calculado na última tentativa (recusa ou revisão) foi aplicado.

Exemplo — recusado 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 revisão 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) fica entre o limiar de recusa (padrão 50) e o limiar de revisão (padrão 70), por isso o aviso traz log_type: "warning" e o status da correspondência facial é In Review. Neste exemplo, o aviso foi disparado em uma sessão cujo session_id é 11111111-2222-3333-4444-555555555555 — source_image_session_id traz o próprio id da sessão porque a referência veio do retrato armazenado na criação da sessão.

Tipos de aviso

Cada risco recebe um tipo de aviso com base na configuração da sua aplicação. Os avisos se dividem em três categorias de gravidade:

Relacionados

Relatório de Autenticação biométrica

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

Avisos de prova de vida

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

Avisos de Correspondência facial

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

Autenticação

Verificação

Monitoramento

Plataforma

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

Visão geral

Onde os avisos aparecem

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 — recusado por ataque facial

Exemplo — em revisão por baixa similaridade

Tipos de aviso

Relacionados

Relatório de Autenticação biométrica

Avisos de prova de vida

Avisos de Correspondência facial

​Visão geral

​Onde os avisos aparecem

​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 — recusado por ataque facial

​Exemplo — em revisão por baixa similaridade

​Tipos de aviso

​Relacionados

Relatório de Autenticação biométrica

Avisos de prova de vida

Avisos de Correspondência facial

Visão geral

Onde os avisos aparecem

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 — recusado por ataque facial

Exemplo — em revisão por baixa similaridade

Tipos de aviso

Relacionados