Para fotografar documento e rosto numa página web, sem aplicativo instalado, o caminho é a API getUserMedia, definida pelo padrão Media Capture and Streams do W3C. Ela pede a câmera ao navegador e devolve um fluxo de vídeo. A resposta curta: o getUserMedia só existe em contexto seguro, depende de permissão da pessoa e trata a maior parte das restrições como preferência, não como garantia; ele entrega quadros de vídeo, e todo o resto da captura de documento, do enquadramento à nitidez, é trabalho da sua página. Pedir a câmera traseira com valor solto é um pedido; pedir com exact é uma exigência que pode falhar.
Em resumo
- A interface é marcada
[SecureContext]no padrão: em página sem HTTPS, ela não existe. - Valor solto ou
idealé preferência;exact,minemaxsão exigências que podem gerarOverconstrainedError. - O padrão define erros distintos para permissão negada, câmera inexistente, câmera ocupada e restrição impossível.
- Ele entrega vídeo; enquadrar, focar e escolher o melhor quadro do documento é trabalho de quem captura.
O que o padrão diz e em que estágio ele está
O Media Capture and Streams é mantido pelo grupo de trabalho de WebRTC do W3C. A versão lida para este texto é o "W3C Candidate Recommendation Draft" de 9 de outubro de 2025, e o próprio documento avisa que ainda não está completo. O método aparece assim na definição de interface: [SecureContext] undefined getUserMedia(MediaStreamConstraints constraints, ...). O atributo [SecureContext] significa que, numa página servida sem HTTPS, o método não está disponível, salvo nos contextos que o navegador trata como seguros, como o endereço local de desenvolvimento.
Restrição é pedido, não ordem
A escolha da câmera e da resolução passa pelas restrições. O padrão define que o navegador "MUST attempt to apply, individually, any 'ideal' constraints or a constraint given as a bare value for the property", e satisfaz o maior número que conseguir. O valor solto, como facingMode: "environment", é tratado como ideal: se o aparelho não tiver câmera traseira, o navegador entrega outra. Já exact, min e max são obrigatórios, e quando nenhuma câmera os atende a promessa é rejeitada com OverconstrainedError.
O valor environment está definido no padrão como "The source is facing away from the user (viewing the environment)", e user como "The source is facing toward the user (a self-view camera)". Para documento, a traseira; para selfie, a frontal.
Na prática, { facingMode: "environment" } pede a traseira e aceita outra; { facingMode: { exact: "environment" } } exige a traseira e falha onde ela não existe. O padrão recomenda o primeiro jeito na maior parte dos casos: os autores de aplicação "are strongly encouraged to use required constraints sparingly", porque cada exigência tira do navegador a margem de escolher a melhor câmera.
O exemplo do próprio padrão mostra a combinação: "width: {min: 640, ideal: 1280}, height: {min: 480, ideal: 720}", um piso que precisa ser atendido e um alvo que o navegador tenta alcançar. A resolução que de fato chegou é lida depois, no getSettings() da trilha de vídeo, e não deve ser presumida.
Os erros que o padrão define, e o que fazer com cada um
| Erro | Quando o padrão o lança | O que a página faz |
|---|---|---|
NotAllowedError | Permissão negada pela pessoa ou pela política da página | Explicar por que a câmera é pedida e como liberar; oferecer outro canal |
NotFoundError | Nenhuma câmera disponível no aparelho | Oferecer continuar em outro aparelho, como o celular |
NotReadableError | Falha de hardware ou trava do sistema, como outro programa usando a câmera | Pedir para fechar o outro programa e tentar de novo |
OverconstrainedError | Restrição obrigatória que nenhuma câmera atende | Repetir o pedido sem exact, com a restrição como ideal |
O padrão ainda prevê o AbortError para falha de acesso por outros motivos. A regra de produto que sai da tabela: cada erro tem uma mensagem própria. Tratar todos como "câmera indisponível" deixa a pessoa sem saber o que fazer.
A permissão também depende da sua página
Antes da pessoa, quem decide é a página. A seção 14 do padrão define a câmera como um recurso controlado por política, com lista padrão de permissão "self", e diz que a política de permissões do documento "determines whether any content in that document is allowed to use getUserMedia". Um cabeçalho Permissions-Policy que negue a câmera faz o pedido falhar mesmo com a pessoa disposta a aceitar, e um iframe de outra origem só usa a câmera se a página que o embute delegar o recurso a ele. Em página com widget embutido, a política da página do integrador vale para o widget. Na UNIFOKAL, a documentação do widget lista o que a página precisa: ser servida por HTTPS, não negar a câmera no Permissions-Policy e ter uma Content-Security-Policy que permita o pacote do widget e o detector de rosto.
O que a captura de documento faz além da API
O getUserMedia entrega quadros de vídeo. A foto de documento que serve para leitura e para conferência é outra coisa, e o trabalho para chegar nela fica com quem constrói a captura. A lista é a leitura da casa, a partir do que a leitura de documento precisa:
- Enquadrar. Guiar a pessoa para o documento ocupar o quadro, sem cortar as bordas, porque a borda é o que mostra que o documento está inteiro.
- Escolher o quadro. Avaliar vários quadros e ficar com o mais nítido, em vez de fotografar no clique.
- Evitar reflexo. Documento plastificado reflete luz; pedir para inclinar ou mudar de posição quando o brilho apaga parte do texto.
- Comprimir com cuidado. A imagem final passa por compressão, e compressão demais apaga detalhe de segurança; o efeito está em compressão JPEG e perícia de documento.
Atenção
O padrão observa que getCapabilities() "gives likely persistent, cross-origin information about the underlying device" e por isso "adds to the fingerprint surface of the device". Consultar as capacidades da câmera para escolher a melhor é legítimo; guardar essas capacidades como identificador do aparelho é outro tratamento de dado, com outra base legal, como explica sinais de dispositivo sem SDK.
Na UNIFOKAL, o OCR do documento lê a foto que a captura entrega. Quanto melhor a captura, menos a leitura precisa adivinhar.
Fontes citadas
- W3C, Media Capture and Streams, W3C Candidate Recommendation Draft de 9 de outubro de 2025, seções de getUserMedia, restrições, VideoFacingModeEnum, erros e integração com a política de permissões (seção 14), em w3.org
- W3C, Media Capture and Streams, rascunho do editor, em w3c.github.io