Integração Web

O Web SDK entrega captura de mídia autenticada direto no navegador: o usuário tira a foto com o componente <provvi-camera> e a Provvi devolve um JPEG com manifesto C2PA + assinatura ICP-Brasil A1 embutidos, autoverificável. Sem app para instalar — funciona numa página web comum, no celular do usuário.

O que a garantia significa (leia antes de posicionar)

A prova do Web SDK é assinatura server-side ICP-Brasil A1 sobre os bytes recebidos — um tier de deterrência de fraude (fraud deterrence). Ela não carrega proveniência de hardware do dispositivo: GPS, bússola e sinais de integridade são telemetria capturada no navegador, não uma âncora criptográfica de origem.

Não faça overclaim. O Web SDK autentica e assina server-side; ele não é uma cadeia de prova com âncora de hardware device-side. Se o seu caso exige proveniência ancorada em hardware (chave por dispositivo, atestação), use o SDK mobile (Android/iOS). O tier fica marcado no próprio manifesto (assurance_level: "fraud_deterrence").

Como funciona — os 4 atores

Quatro partes conversam ao longo de uma captura. A x-api-key vive só no seu backend; o frontend recebe apenas um token de sessão descartável.

┌────────────────────┐        ┌──────────────┐        ┌─────────────────────────┐
│  Seu backend       │        │   Provvi     │        │  Navegador do usuário   │
│  (guarda a         │        │   (API +     │        │  <provvi-camera>        │
│   x-api-key)       │        │   assinatura)│        │  (SDK)                  │
└─────────┬──────────┘        └──────┬───────┘        └────────────┬────────────┘
          │                          │                             │
   (1) POST /web/sessions            │                             │
          │  x-api-key ─────────────▶│                             │
          │◀──────────── { token } ──│                             │
          │                          │                             │
   (2) entrega o token ──────────────────────────────────────────▶│
          │                          │                             │
          │                          │◀── (3) GET sessão / POST ───│
          │                          │        ingest (captura)     │
          │                          │─── (4) imagem assinada + ──▶│
          │                          │        manifest_url INLINE  │
          │                          │                             │

Os passos numerados acima são os mesmos da barra lateral:

Criar a sessão — seu backend chama POST /web/sessions com a x-api-key e recebe { token, expires_at }.
Embutir o componente — sua página carrega o SDK da CDN e entrega o token ao <provvi-camera>.
Ciclo de captura — open({ token }) abre a câmera, o SDK captura, faz upload e a Provvi assina com ICP-Brasil; você acompanha por eventos do DOM.
Tratar erros — browser bloqueado, GPS, recaptura, sessão expirada: cada um com uma ação clara para o usuário.
Receber o resultado — o SDK devolve a imagem autenticada + a URL do manifesto INLINE, no evento de conclusão da captura (sem webhook nem consulta), e você verifica o manifesto.
Configuração da conta — perfis, política de armazenamento, verificação de localização, domínios autorizados e limites.

Hosted Flow (fora no momento): a captura hospedada pela Provvi (sem embutir o componente) foi descontinuada e será redesenhada do zero com contrato próprio. Hoje a integração web é via componente Web SDK, descrito nesta jornada.

Regra de ouro

A x-api-key (pvv_api_*) nunca desce ao frontend. Quem tem essa chave cria sessões e obtém imagens assinadas com ICP-Brasil sob a sua conta. Se ela aparecer no navegador (view-source, aba de rede), qualquer pessoa forja capturas no seu nome e consome sua cota. Mantenha-a server-side, sempre. O frontend só vê o token de sessão — descartável e de uso único.

A license_key (pvv_*), ao contrário, pode ficar no frontend: ela é desenhada para isso e sua admissão é controlada pelos domínios autorizados (origin-scoping) da sua conta.

O que pedir à Provvi antes de começar

Você recebe estas credenciais e configurações no admin-console (admin.provvi.com.br). O detalhe de cada item está no Passo 6 — Configuração.

Item	O que é	Onde vive
API key (`pvv_api_*`)	Cria sessões de captura. Credencial de alto privilégio.	Só no seu backend.
License key (`pvv_*`)	Licencia o SDK no navegador.	Frontend (admissão por domínio).
Domínios autorizados	Origin-scoping: a license só é aceita nos domínios registrados.	Configuração da conta.
`store_asset_policy`	Se a Provvi entrega o JPEG assinado ou só o manifesto (`ALWAYS` / `NEVER` / `PER_SESSION`).	Configuração da conta.
`gps_mode`	Verificação de localização (`off` / `report_only` / `enforce`).	Configuração da conta.

Navegadores suportados

O Web SDK exige um navegador móvel com acesso à câmera. A lista é restritiva por design — o que não estiver aqui é bloqueado com um erro claro (BROWSER_NOT_SUPPORTED), não degradado.

Ambiente	Suporte
Safari no iPhone/iPad	✅ Suportado
Chrome no Android	✅ Suportado
Firefox (qualquer plataforma)	❌ Bloqueado
Chrome, Edge, Opera no iOS	❌ Bloqueado (no iOS, use o Safari)
Qualquer navegador de desktop	❌ Bloqueado

Captura só no celular. A câmera não abre em desktop (nem em navegador fora da allowlist). Cheque camera.isUserAgentSupported() antes de abrir e conduza o usuário no seu próprio fluxo quando o navegador não for suportado.

HTTPS é obrigatório. A câmera (getUserMedia) e o hash (SubtleCrypto) não funcionam em origem insegura — sirva sua página por https:// (ou http://localhost em dev).

Próximo passo → Criar a sessão