> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Avisos de prova de vida (liveness) e códigos de erro

> Avisos do módulo de liveness da Didit: ataques faciais, pontuação baixa, qualidade, lista de bloqueio e rostos duplicados, com causa e solução.

## Visão geral

Os avisos do relatório de prova de vida sinalizam cada condição que a Didit observou ao executar a verificação de prova de vida. Eles aparecem no array `warnings[]` de cada item de `liveness_checks[]` (consulte o [relatório de prova de vida](https://docs.didit.me/pt-br/core-technology/liveness/report-liveness.md)), com `feature` definido como `"LIVENESS"`. Cada entrada segue o formato compartilhado do [objeto de aviso](https://docs.didit.me/pt-br/reference/data-models.md#objeto-de-aviso): `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`.

Todo aviso tem três camadas:

1. **O código `risk`**: um identificador estável que você pode usar para correspondência no seu código (os códigos listados abaixo).
2. **O `log_type`**: um dentre `information`, `warning` ou `error`. Os riscos de recusa automática sempre têm `error`. Para riscos configuráveis, ele é derivado da ação configurada: **No action** → `information`, **Review** → `warning`, **Decline** → `error`. Para riscos baseados em limiar (`LOW_LIVENESS_SCORE`, `LOW_FACE_QUALITY`), ele é `error` quando o valor ultrapassa o limiar de recusa e `warning` quando ultrapassa apenas o limiar de revisão.
3. **O impacto na decisão**: o mesmo roteamento define o `status` do relatório de prova de vida: uma ação de Revisão o move para `In Review`, uma ação de Recusar (ou qualquer risco de recusa automática) para `Declined`, e Sem ação o mantém inalterado.

Alguns riscos são emitidos apenas quando o método de prova de vida é `PASSIVE` (verificações de múltiplos rostos, qualidade e luminância). As tabelas abaixo listam o conjunto completo de códigos de risco de prova de vida e suas severidades; não existem outros códigos de risco de prova de vida.

## Condições de recusa automática

Os riscos a seguir sempre fazem com que o relatório de prova de vida (e a sessão) passe para `Declined`, com `log_type: "error"`:

| Risco | Gatilho |
| - | - |
| `NO_FACE_DETECTED` | Nenhum rosto foi localizado durante a captura de prova de vida, ou o usuário esgotou as tentativas. |
| `LIVENESS_FACE_ATTACK` | O modelo detectou um ataque de apresentação (máscara, reprodução em tela, spoofing do tipo deepfake). |
| `FACE_IN_BLOCKLIST` | O rosto correspondeu a uma entrada na lista de bloqueio de rostos da sua aplicação. |
| `AGE_BELOW_MINIMUM` | Idade estimada abaixo do mínimo configurado. Emitido apenas em fluxos de verificação de idade adaptativos e em nós `AGE_ESTIMATION`. |
| `AGE_NOT_DETECTED` | Não foi possível estimar a idade. Emitido apenas em fluxos de estimativa de idade com o fallback para verificação de identidade desativado. |

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

## Configurações de verificação ajustáveis

No console da Didit, os riscos de prova de vida são agrupados nas seguintes configurações do fluxo de verificação (workflow):

| Grupo | Riscos | Configuração |
| - | - | - |
| **Limiares de pontuação de prova de vida** | `LOW_LIVENESS_SCORE` | Limiar de revisão + limiar de recusa sobre `score`. Igual ou abaixo do de revisão → `In Review`; igual ou abaixo do de recusa → `Declined`. |
| **Ação para rosto duplicado** | `DUPLICATED_FACE`, `POSSIBLE_DUPLICATED_FACE` | Uma configuração compartilhada: Sem ação (padrão) / Revisão / Recusar. Ignorada por completo quando o rosto correspondente está na sua lista de permissão de rostos. |
| **Divergência de identidade em rosto duplicado** | `DUPLICATED_FACE_NAME_MISMATCH` | Configuração própria (`face_liveness_duplicated_face_name_mismatch_action`): Sem ação / Revisão (padrão) / Recusar. Avaliada apenas quando `DUPLICATED_FACE` também é disparado; veja abaixo. |
| **Correspondência com rosto de ataque de prova de vida** | `FACE_MATCHES_LIVENESS_ATTACK` | Configuração própria (`face_liveness_attack_face_match_action`): Sem ação (padrão) / Revisão. A opção Recusar definida aqui é aceita, mas aplicado como Revisão. Também disponível no nó de Estimativa de idade. |
| **Possível rosto na lista de bloqueio** | `POSSIBLE_FACE_IN_BLOCKLIST` | Não configurável nos fluxos: sempre encaminhado para Revisão (`log_type: "warning"`). |
| **Ação para múltiplos rostos** *(somente passiva)* | `MULTIPLE_FACES_DETECTED` | Sem ação (padrão) / Revisão / Recusar. |
| **Limiares de qualidade facial** *(somente passiva)* | `LOW_FACE_QUALITY` | Limiar de revisão (padrão 15) + limiar de recusa (padrão 0, ou seja, recusa desativada). |
| **Luminância facial** *(somente passiva)* | `LOW_FACE_LUMINANCE`, `HIGH_FACE_LUMINANCE` | Limiares mínimo / máximo (padrões 20 / 80 na escala normalizada de 0–100) + uma ação para cada direção (padrão Revisão). |
| **Limiares de idade** *(fluxos adaptativos / nó `AGE_ESTIMATION`)* | `AGE_BELOW_MINIMUM`, `AGE_NOT_DETECTED` | Limiares de idade mínima e limítrofe; ambos os riscos resultam na recusa automática da etapa de prova de vida. Com o fallback para verificação de identidade ativado, o fluxo encaminha o usuário para uma verificação de documento em vez de encerrar a sessão. |

## Avisos gerados

### Prova de vida principal

| Risco | Causa | Gravidade | Afeta o status? | Correção |
| - | - | - | - | - |
| `NO_FACE_DETECTED` | Nenhum rosto foi localizado durante a captura, ou o usuário esgotou as tentativas (`MAX_ATTEMPTS_REACHED`). | `error` | **Recusa automática** | Capture novamente com iluminação melhor e garanta que o rosto esteja centralizado. |
| `LIVENESS_FACE_ATTACK` | O modelo detectou um ataque de apresentação. | `error` | **Recusa automática** | Trate como fraude. A sessão é recusada automaticamente. |
| `LOW_LIVENESS_SCORE` | `score` igual ou abaixo do limiar de revisão do fluxo de verificação (workflow). É suprimido quando `NO_FACE_DETECTED` também está presente. | `warning`; passa a `error` quando a pontuação está igual ou abaixo do limiar de recusa | Configurável (limiares de revisão e de recusa) | Capture novamente; ajuste os limiares se observar falsos positivos. |

### Integridade do canal de captura

Sinais de ataque de injeção informados pelo cliente no momento da captura. Diferentemente dos ataques de apresentação (um artefato exibido diante de uma câmera real), eles indicam que o próprio feed da câmera foi substituído ou interceptado.

Cada um é configurável por fluxo e tem como padrão **nenhuma ação**, então ativar o recurso não altera nenhuma decisão até que você opte por isso.

| Risco | Causa | Chave de configuração | Padrão |
| - | - | - | - |
| `VIRTUAL_CAMERA_DETECTED` | O dispositivo de captura foi identificado como uma câmera virtual de software (OBS, ManyCam, Snap Camera, DroidCam e similares), e não como uma câmera física. | `virtual_camera_action` | `NO_ACTION` |
| `EXTERNAL_CAPTURE_DEVICE_DETECTED` | O dispositivo de captura era uma câmera externa ou uma placa de captura, e não uma câmera integrada. | `external_capture_device_action` | `NO_ACTION` |
| `FRAME_INJECTION_SUSPECTED` | Os frames capturados apresentam indícios de composição por software ou de injeção no pipeline da câmera, e não de uma captura ao vivo genuína, **ou** a captura foi feita em hardware emulado ou virtualizado (um emulador Android ou uma máquina virtual de desktop), onde não existe sensor de câmera físico e todos os frames são fornecidos pelo host. | `frame_injection_action` | `NO_ACTION` |
| `INJECTION_ATTACK_DETECTED` | A captura foi injetada, e não feita pela própria câmera do dispositivo: uma câmera virtual de software, um feed de câmera gerado pela página ou por automação do navegador, uma câmera interceptada por um hook ou uma ferramenta de instrumentação conectada ao app. `additional_data.reasons` lista apenas os motivos que comprovam a injeção. Sinais que uma pessoa genuína pode produzir nunca o disparam. Na prova de vida e na correspondência facial, ele segue `frame_injection_action`, então as decisões sobre a selfie não mudam. | `frame_injection_action` | `NO_ACTION` |
| `SCREEN_CAPTURE_DURING_CAPTURE` | A gravação ou o compartilhamento de tela estava ativo no dispositivo durante a captura biométrica. | `screen_capture_action` | `NO_ACTION` |

> [!NOTE]
>
> Os navegadores não oferecem a nenhum fornecedor atestação da origem da câmera no nível do sistema operacional, então, na web, esses sinais são evidências complementares, e não constituem prova. Na web, um veredito `null` significa **não determinado** (os rótulos dos dispositivos ficam indisponíveis até que a permissão da câmera seja concedida) e nunca dispara um risco.

Uma câmera virtual é identificada pelo nome do dispositivo, então uma câmera que o sistema operacional apresenta com um nome comum não é reconhecida dessa forma. Dentro de um emulador Android, a câmera remapeada recebe um rótulo igual ao de qualquer câmera integrada, e é por isso que o caso de hardware emulado é informado por meio de `FRAME_INJECTION_SUSPECTED`: ele é detectado a partir do ambiente do dispositivo (a pilha de renderização e o modelo do dispositivo informado no user agent), e não pelo nome da câmera. As ocorrências geradas a partir do ambiente do dispositivo trazem `additional_data.reason: "emulated_capture_device"`, o que as distingue da análise de frames feita pelo próprio modelo de prova de vida.

> [!NOTE]
>
> Detectar a máquina a partir de um navegador é uma evidência, não uma atestação, e um invasor determinado pode interferir nisso. Os SDKs mobile nativos informam sinais de integridade mais fortes, no nível do sistema operacional, que um navegador não consegue ver (emulador, dispositivo com root ou jailbreak, hooking em tempo de execução, depurador conectado), cada um com sua própria ação configurável em [Integridade do dispositivo e do ambiente de execução](https://docs.didit.me/pt-br/core-technology/ip-analysis/warnings-ip-analysis.md#integridade-do-dispositivo-e-do-ambiente-de-execução). Esses sinais aumentam consideravelmente o custo para o invasor, mas, sozinhos, não comprovam que uma captura veio de um dispositivo genuíno. Os sinais de integridade do dispositivo são independentes do método de prova de vida, então podem ser combinados com qualquer um dos métodos Passive, 3D Flash ou 3D Action & Flash.

### Análise forense de consistência da gravação

`LIVENESS_VIDEO_ANOMALY` é calculado **no servidor, sobre a gravação de prova de vida armazenada**, de forma independente do modelo de prova de vida. Ele detecta uma sequência em movimento repetida em vários ciclos, compatível com um feed em loop.

| Risco | Causa | Chave de configuração | Padrão |
| - | - | - | - |
| `LIVENESS_VIDEO_ANOMALY` | A gravação contém uma sequência em movimento repetida. Travamentos da câmera, frames estáticos repetidos, inícios escuros e entrega lenta de frames, por si só, não disparam esse sinal. | `face_liveness_video_anomaly_action` | `NO_ACTION` |

Defina a ação no seu nó de Liveness ou de Age Estimation: `NO_ACTION` registra uma ocorrência informativa, `REVIEW` pode escalar uma verificação cuja decisão já foi tomada para Em revisão e `DECLINE` pode escalá-la para Recusado. A verificação é executada de forma assíncrona, então uma escalada pode chegar depois do resultado inicial. Uma decisão existente mais severa não é rebaixada, e as decisões de revisão manual são preservadas.

As ocorrências da versão 2 incluem `forensics_version: 2`, a evidência `repeated_sequence` e `repeated_moving_sequence` em `anomaly_reasons`. Medições de entrega, como `unique_frame_ratio`, `static_pair_ratio`, `decoded_fps_ratio` e `max_frame_gap_seconds`, continuam sendo diagnósticas; sozinhas, elas não conseguem comprovar uma reprodução. As ocorrências mais antigas descrevem a versão do detector usada na época e não são reclassificadas retroativamente.

> [!NOTE]
>
> Este é um sinal adicional conservador, e não uma detecção completa de mídia sintética ou de vídeo injetado. Uma gravação sem anomalia não é prova de vida. Capturas curtas ou ambíguas e capturas sem evidência utilizável de reprodução não são sinalizadas por esta verificação. Gravações ausentes ou ilegíveis não geram ocorrência nesta verificação; as demais verificações continuam valendo.

### Correspondência facial entre sessões

| Risco | Causa | Dados adicionais | Severidade |
| - | - | - | - |
| `FACE_IN_BLOCKLIST` | O rosto correspondeu a um rosto da lista de bloqueio. | `blocklisted_session_id`, `blocklisted_session_number`, `api_service` | `error` — **recusa automática** |
| `POSSIBLE_FACE_IN_BLOCKLIST` | O rosto correspondeu a um rosto da lista de bloqueio em uma faixa de confiança mais baixa. | `blocklisted_session_id`, `blocklisted_session_number`, `api_service` | `warning` — sempre encaminhado para revisão nos fluxos |
| `FACE_IN_ALLOWLIST` | O rosto correspondeu a um rosto da lista de permissões. | `allowlisted_session_id`, `allowlisted_session_number`, `api_service` | `information` — a ação de rosto duplicado é ignorada |
| `POSSIBLE_FACE_IN_ALLOWLIST` | O rosto correspondeu a um rosto da lista de permissões em uma faixa de confiança mais baixa. | `allowlisted_session_id`, `allowlisted_session_number`, `api_service` | `information` — a ação de possível rosto duplicado é ignorada |
| `DUPLICATED_FACE` | O rosto correspondeu a um rosto já aprovado de outro usuário (uma sessão `Approved` com `vendor_data` diferente, ou um rosto importado vinculado a um dos seus usuários vendor). | `duplicated_session_id`, `duplicated_session_number`, `api_service` | Configurável — `information` por padrão |
| `POSSIBLE_DUPLICATED_FACE` | O rosto correspondeu a outro rosto aprovado ou importado em uma faixa de confiança mais baixa. | `duplicated_session_id`, `duplicated_session_number`, `api_service` | Configurável — `information` por padrão |
| `DUPLICATED_FACE_NAME_MISMATCH` | Emitido junto com `DUPLICATED_FACE` quando a identidade da sessão correspondente não coincide com o nome resolvido desta sessão (documento de identidade, `expected_details` ou usuário vendor vinculado), usando a mesma pontuação de correspondência de nomes e o mesmo limiar da verificação de identidade. Um rosto reutilizado com outro nome é um sinal de fraude mais forte do que uma simples duplicata, por isso tem sua própria ação configurável. | `duplicated_session_id`, `duplicated_session_number`, `api_service`, `name_match_score` | Configurável — `warning` por padrão. Nunca abranda o resultado configurado do próprio `DUPLICATED_FACE`, apenas o agrava. |
| `DUPLICATED_FACE_DOCUMENT_MISMATCH` | Emitido junto com `DUPLICATED_FACE` quando o documento de identidade do usuário correspondente mostra uma data de nascimento diferente da do documento desta sessão. A mesma pessoa apresentando um documento diferente (por exemplo, um passaporte depois de uma carteira de identidade) ou um documento renovado não é sinalizada, e duas sessões que compartilham o mesmo número de documento do mesmo país nunca são sinalizadas. | `duplicated_session_id`, `duplicated_session_number`, `api_service`, `mismatch_dimensions` | Configurável (`face_liveness_duplicated_face_document_mismatch_action`) - `Review` por padrão. Nunca abranda o resultado configurado do próprio `DUPLICATED_FACE`, apenas o agrava. |
| `FACE_MATCHES_LIVENESS_ATTACK` | O rosto corresponde a um rosto de uma sessão anterior desta aplicação, de outro usuário, cuja própria captura de prova de vida foi considerada um ataque com alta confiança. É uma evidência para revisão, não uma prova de ataque. | `liveness_attack_session_id`, `liveness_attack_session_number`, `similarity_percentage`, `liveness_attack_sessions_count` | Configurável - `information` por padrão (nenhuma ação) |

Para correspondências com rostos importados ou rostos de entradas de lista (que não têm sessão), os valores `*_session_id`, `*_session_number` e `api_service` em `additional_data` são `null`.

Rostos que pertencem ao mesmo usuário (mesmo `vendor_data`, ou o mesmo usuário vendor quando disponível) são excluídos de **toda** a busca no índice — tanto da detecção de duplicatas quanto da triagem na lista de bloqueio. A ordem de precedência das correspondências é: lista de bloqueio exata → lista de permissões exata → duplicata exata → lista de bloqueio possível → lista de permissões possível → duplicata possível — apenas um desses seis códigos mutuamente exclusivos aparece por relatório. `DUPLICATED_FACE_NAME_MISMATCH` não faz parte desse grupo de precedência: é um código adicional emitido **além de** `DUPLICATED_FACE` quando a verificação de identidade também falha, nunca no lugar dele. `additional_data.name_match_score` nunca contém os nomes comparados — apenas IDs e uma pontuação, para que nenhum dado pessoal (PII) chegue ao payload do aviso.

Um nome escrito em um sistema de escrita diferente em cada documento (por exemplo, hebraico em um e latino no outro) pode ficar abaixo do limiar mesmo quando as duas sessões pertencem à mesma pessoa. Somente nesse caso, `DUPLICATED_FACE_NAME_MISMATCH` não é emitido quando os documentos de identidade das duas sessões se corroboram em todos estes pontos:

* Os dois documentos têm o mesmo país emissor.
* Um identificador coincide exatamente entre os dois documentos. `document_number` e `personal_number` contam de forma intercambiável, porque o mesmo número nacional pode estar em qualquer um dos dois campos, dependendo do tipo de documento.
* Quando os dois documentos têm data de nascimento, ela é a mesma.

Se os nomes estiverem no mesmo sistema de escrita, se o identificador ou o país emissor for diferente ou estiver ausente, ou se as datas de nascimento se contradisserem, o aviso continua sendo emitido conforme descrito acima.

### Qualidade da prova de vida passiva (somente quando `method = "PASSIVE"`)

| Risco | Causa | Severidade | Correção |
| - | - | - | - |
| `MULTIPLE_FACES_DETECTED` | Mais de um rosto ficou visível durante a captura. O maior rosto é sempre usado para a pontuação e a correspondência. | Configurável — `information` por padrão | Faça uma nova captura sem outras pessoas. |
| `LOW_FACE_QUALITY` | Qualidade do rosto abaixo do limiar de revisão (padrão 15). | `warning`; `error` quando abaixo do limiar de recusa (padrão 0 — recusa desativada) | Melhor foco / menos obstrução / rosto centralizado. |
| `LOW_FACE_LUMINANCE` | Luminância normalizada abaixo do limiar mínimo (padrão 20). | Configurável — `warning` por padrão (a ação padrão é revisão) | Melhor iluminação. |
| `HIGH_FACE_LUMINANCE` | Luminância normalizada acima do limiar máximo (padrão 80). | Configurável — `warning` por padrão (a ação padrão é revisão) | Reduzir a iluminação; evitar luz de fundo. |

`LOW_FACE_LUMINANCE` e `HIGH_FACE_LUMINANCE` são mutuamente exclusivos — a luminância está abaixo do mínimo ou acima do máximo, nunca as duas coisas.

### Estimativa de idade (fluxos adaptativos e nós `AGE_ESTIMATION`)

| Risco | Causa | Gravidade | Correção |
| - | - | - | - |
| `AGE_BELOW_MINIMUM` | Idade estimada abaixo do mínimo configurado (ou do limiar para casos limítrofes quando o fallback para verificação de identidade está ativado). | `error` | O fluxo recorre à verificação de identidade quando isso está configurado. |
| `AGE_NOT_DETECTED` | Não foi possível estimar a idade e o fallback para verificação de identidade está desativado. | `error` | Ative o fallback ou faça uma nova captura. |

## Strings exatas de descrição

A API retorna exatamente estas strings de `short_description` e `long_description` para cada risco:

| `risk` | `short_description` | `long_description` |
| - | - | - |
| `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 ser causado 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. |
| `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 que não são de uma pessoa ao vivo ou dados biométricos de baixa qualidade. |
| `LIVENESS_VIDEO_ANOMALY` | Anomalia no fluxo de vídeo da prova de vida | O vídeo gravado da prova de vida contém uma sequência de movimento repetida, compatível com uma transmissão em loop. Travamentos da câmera, quadros estáticos repetidos e entrega lenta de quadros, por si sós, não geram este sinal. Esta é uma verificação independente da gravação, e não uma avaliação completa de se a captura é ao vivo. |
| `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 relacionadas a possíveis rostos duplicados 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 um nome diferente | O mesmo rosto já foi aprovado em outra sessão, mas com um nome diferente. A identidade por trás do duplicado não corresponde à identidade declarada nesta sessão, o que é um forte indício de fraude de identidade. |
| `FACE_MATCHES_LIVENESS_ATTACK` | Rosto corresponde a um ataque à prova de vida | O rosto desta captura de prova de vida corresponde a um rosto de uma sessão anterior desta aplicação, de outro usuário, cuja própria captura foi considerada pelo mecanismo de prova de vida como um ataque com alta confiança. Um usuário legítimo pode ser rejeitado por engano, por isso este é um sinal para revisão, e não uma prova de ataque. |
| `MULTIPLE_FACES_DETECTED` | Vários rostos detectados | Foram detectados vários rostos na imagem da 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` | Baixa qualidade do rosto | A qualidade da imagem facial está abaixo do limiar aceitável, o que pode afetar a confiabilidade da prova de vida. Isso pode ser causado pela resolução da câmera, pelo foco ou por artefatos de compressão. |
| `LOW_FACE_LUMINANCE` | Baixa luminância do rosto | A imagem facial está escura demais, o que pode afetar a precisão da prova de vida. Recomenda-se melhorar as condições de iluminação. |
| `HIGH_FACE_LUMINANCE` | Alta luminância do rosto | A imagem facial está clara demais ou superexposta, o que pode afetar a precisão da prova de vida. Recomenda-se reduzir a iluminação ou evitar luz direta. |
| `AGE_BELOW_MINIMUM` | Idade abaixo do mínimo | A idade do rosto está abaixo do limiar de idade mínima da aplicação. |
| `AGE_NOT_DETECTED` | Idade não detectada | O sistema não conseguiu identificar a idade do rosto, o que é necessário para a verificação do documento. |

## API de prova de vida passiva independente

A [API de prova de vida](https://docs.didit.me/pt-br/standalone-apis/passive-liveness.md) independente reutiliza os mesmos códigos de risco, com algumas diferenças de comportamento:

* `NO_FACE_DETECTED` e `LOW_LIVENESS_SCORE` são mutuamente exclusivos: a verificação da pontuação só é executada quando um rosto é encontrado. `LOW_LIVENESS_SCORE` é disparado com base no `face_liveness_score_decline_threshold` da requisição (padrão 30) e sempre vem com `log_type: "error"`.
* `POSSIBLE_FACE_IN_BLOCKLIST` é tratado como recusa (`log_type: "error"`), e não como revisão.
* `MULTIPLE_FACES_DETECTED` vem com `log_type: "warning"`, enquanto os riscos de rosto duplicado continuam apenas informativos. Somente avisos de nível `error` mudam o `status` da resposta independente para `Declined`.
* As entradas de aviso da API independente incluem `feature`, mas não `node_id`.

## Exemplos

### Recusa automática por ataque detectado

```json theme={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": "liveness_primary"
  }
]
```

### Avisos configuráveis em uma captura passiva

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "LOW_FACE_QUALITY",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "Low face quality",
    "long_description": "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.",
    "node_id": "liveness_primary"
  },
  {
    "feature": "LIVENESS",
    "risk": "LOW_FACE_LUMINANCE",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "Low face luminance",
    "long_description": "The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.",
    "node_id": "liveness_primary"
  },
  {
    "feature": "LIVENESS",
    "risk": "MULTIPLE_FACES_DETECTED",
    "additional_data": null,
    "log_type": "information",
    "short_description": "Multiple faces detected",
    "long_description": "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.",
    "node_id": "liveness_primary"
  }
]
```

### Rosto duplicado com payload

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "DUPLICATED_FACE",
    "additional_data": {
      "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
      "duplicated_session_number": 123,
      "api_service": null
    },
    "log_type": "warning",
    "short_description": "Duplicated face from other approved session",
    "long_description": "The system identified a duplicated face from another approved session, requiring further investigation.",
    "node_id": "liveness_primary"
  }
]
```

Aqui, a ação para rosto duplicado está definida como Revisão, então o aviso traz `log_type: "warning"` e o status do relatório de prova de vida é `In Review`. Com o padrão (Nenhuma ação), ele traria `log_type: "information"`. `api_service` é `null` porque o rosto correspondente veio de uma sessão de fluxo de verificação (workflow), e não de uma chamada avulsa à API.

### Rosto duplicado com outro nome

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "DUPLICATED_FACE",
    "additional_data": {
      "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
      "duplicated_session_number": 123,
      "api_service": null
    },
    "log_type": "information",
    "short_description": "Duplicated face from other approved session",
    "long_description": "The system identified a duplicated face from another approved session, requiring further investigation.",
    "node_id": "liveness_primary"
  },
  {
    "feature": "LIVENESS",
    "risk": "DUPLICATED_FACE_NAME_MISMATCH",
    "additional_data": {
      "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
      "duplicated_session_number": 123,
      "api_service": null,
      "name_match_score": 42.5
    },
    "log_type": "warning",
    "short_description": "Duplicated face under a different name",
    "long_description": "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.",
    "node_id": "liveness_primary"
  }
]
```

`DUPLICATED_FACE` mantém a própria ação configurada (aqui, Nenhuma ação, com `log_type: "information"`), enquanto `DUPLICATED_FACE_NAME_MISMATCH` tem a própria ação, que por padrão é Revisão (`log_type: "warning"`). O status do relatório de prova de vida segue a mais severa das duas: `In Review` neste caso, embora a configuração de rosto duplicado sozinha não o tivesse sinalizado.

### Anomalia de integridade da gravação com suas medições

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "LIVENESS_VIDEO_ANOMALY",
    "additional_data": {
      "forensics_version": 2,
      "duration_seconds": 6.0,
      "repeated_sequence": {
        "period_frames": 6,
        "cycles": 3,
        "matched_pairs": 12
      },
      "anomaly_reasons": ["repeated_moving_sequence"]
    },
    "log_type": "information",
    "short_description": "Liveness video stream anomaly",
    "long_description": "The recorded liveness video contains a repeated moving sequence consistent with a looped feed. Camera stalls, repeated still frames and slow frame delivery alone do not raise this signal. This is an independent recording check, not a complete assessment of whether the capture is live.",
    "node_id": "liveness_primary"
  }
]
```

Este exemplo mostra as evidências de replay de uma gravação que contém três cópias de uma sequência em movimento. `log_type` é `information` porque a ação configurada é `NO_ACTION`. Os diagnósticos de entrega de frames, omitidos deste exemplo por questões de concisão, não acionam a detecção.

## Tipos de aviso

Cada risco recebe um nível de severidade com base na configuração da sua aplicação. As três severidades são:

## Relacionados

* [Relatório de prova de vida](https://docs.didit.me/pt-br/core-technology/liveness/report-liveness.md): esquema completo do relatório e status.
* [Avisos de correspondência facial](https://docs.didit.me/pt-br/core-technology/face-match/warnings-face-match.md): avisos complementares de correspondência facial 1:1.
* [Webhooks](https://docs.didit.me/pt-br/integration/webhooks.md): `session.status.updated` traz os avisos assim que a etapa de prova de vida termina.
* [Modelos de dados: verificação de prova de vida](https://docs.didit.me/pt-br/reference/data-models.md#verificação-de-prova-de-vida): esquema canônico com todos os campos.
* [Modelos de dados: objeto de aviso](https://docs.didit.me/pt-br/reference/data-models.md#objeto-de-aviso): o formato de cada entrada em `warnings[]`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.