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

# Selfie com prova de vida passiva

> O módulo passive_liveness faz a prova de vida com uma selfie, sem desafio, e compara a selfie com o documento do mesmo flow quando ele existe, com o payload de resultado.

## Selfie com prova de vida passiva

O módulo `passive_liveness` faz a prova de vida com **uma selfie**, sem desafio de movimento. O titular tira a foto de perto e o widget guarda alguns quadros logo depois dela. Sobre essa captura rodamos a detecção de ataque de apresentação (como foto impressa ou tela) e devolvemos uma pontuação de vivacidade de 0 a 100 com a faixa `real`, `ambiguous` ou `spoof`.

Quando o mesmo flow lê um documento (`cpf_ocr` ou `doc_global`), o módulo também compara a selfie com o rosto do documento e devolve o resultado em `match`. A referência é sempre o documento lido por esse módulo do flow: sem ele no flow, nenhuma imagem de documento enviada pela sessão é usada e o `match` sai `not_requested`; com ele no flow e sem a imagem, o módulo não decide sem a comparação e não é cobrado. Por já incluir essa comparação, ele não entra no mesmo flow que o `face`: a API recusa a combinação com 422 `passive_liveness_includes_face_match`. O módulo não tem dependência e não substitui o `liveness` onde outro módulo exige a prova de vida com desafio.

```
// passive_liveness no check_details: selfie confirmada e mesma pessoa do documento
{ "module": "passive_liveness", "passed": true, "outcome": "approved",
  "data": {
    "status": "approved",
    "liveness": { "score": 97, "band": "real", "calibration_version": "2026-10-01",
                  "evidence_level": "sequence" },
    "face": { "count": 1, "quality": 88, "bbox": [212, 148, 236, 296] },
    "match": { "status": "match", "similarity": 74, "reference": "document" },
    "warnings": [] } }

// passive_liveness sem documento no flow: o match não é pedido
{ "module": "passive_liveness", "passed": true, "outcome": "approved",
  "data": {
    "status": "approved",
    "liveness": { "score": 95, "band": "real", "calibration_version": "2026-10-01",
                  "evidence_level": "sequence" },
    "face": { "count": 1, "quality": 90, "bbox": [204, 152, 240, 300] },
    "match": { "status": "not_requested", "similarity": null, "reference": null },
    "warnings": [{ "code": "match_reference_missing", "severity": "info" }] } }

// passive_liveness: ataque de apresentação (portão duro: reprova)
{ "module": "passive_liveness", "passed": false, "outcome": "failed",
  "data": {
    "status": "declined",
    "liveness": { "score": 8, "band": "spoof", "calibration_version": "2026-10-01",
                  "evidence_level": "sequence" },
    "face": { "count": 1, "quality": 64, "bbox": [198, 140, 250, 310] },
    "match": { "status": "unavailable", "similarity": null, "reference": null },
    "warnings": [{ "code": "presentation_attack", "severity": "error" }] } }
```

O `status` é um de quatro: `approved`, `declined`, `recapture` (a foto não serviu e o titular tira outra) e `review` (revisão humana, como na faixa `ambiguous` ou no match com pouca folga). O mesmo valor sai no resumo: `"checks": { ... "passive_liveness": "approved" }`. O `evidence_level` diz o que sustentou a pontuação: `sequence` quando os quadros depois da selfie chegaram e confirmaram a foto, `single_image` quando só a imagem única estava disponível. A `sequence` só vale quando os quadros mostram o mesmo rosto da selfie: quadros de outra pessoa ao lado da selfie contam como `single_image`. Com `single_image` a resposta traz o aviso `single_image_evidence`, o `status` sai `review` e a verificação vai à revisão humana: a imagem única nunca aprova no automático, porque uma imagem só sustenta menos que a sequência. No sandbox, o documento terminado em `11` devolve a imagem única e o terminado em `22` devolve quadros de outro rosto, os dois com a verificação em revisão, como em produção.

A lista de avisos é fechada, cada um com a severidade: `no_face_detected`, `multiple_faces`, `presentation_attack`, `face_mismatch` e `face_in_blocklist` (`error`); `low_face_quality` e `liveness_ambiguous` (`warning`); `match_reference_missing` e `single_image_evidence` (`info`). O bloco não traz idade, gênero nem vetor biométrico. A pontuação e a similaridade só viajam para o seu servidor, no webhook e no GET com a chave secreta, nunca para o navegador. Para a prova de vida com desafio, veja o [liveness](https://docs.unifokal.com/modulos/identidade.md#modulo-liveness); o preço está na [tabela de preços](https://unifokal.com/precos).


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