Pular para o conteúdo
Provvi Docs

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>, o SDK envia o frame e a Provvi assina um JPEG com manifesto C2PA + assinatura ICP-Brasil A1 embutidos, autoverificável. O evento de conclusão traz { session_id, authenticated_jpeg_url }; a URL do JPEG só vem preenchida quando a política de armazenamento da sua conta é ALWAYS (ver Passo 6 · Configuração). Sem app para instalar — funciona numa página web comum, no celular do usuário.

O que a garantia significa (leia antes de posicionar)

Seção intitulada “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

Seção intitulada “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) uploaded: ──────────▶│
          │                          │     session_id + jpeg_url*  │
          │                          │                             │

* authenticated_jpeg_url vem null quando a política de armazenamento da conta é NEVER; nesse caso o sidecar do manifesto fica disponível ao seu backend em GET /web/session-results/:token enquanto o registro da sessão existir — busque e guarde o manifest_url logo após o evento uploaded; a Provvi não garante a rota depois dos 30 minutos de validade da sessão.

Nota (2026-09-21). Desde 2026-09-20 a resposta do POST /web/ingest entrega o JPEG assinado inline (campo signed_image_base64), em qualquer política de armazenamento. O componente <provvi-camera> publicado não expõe esse campo ao seu código — o fluxo acima continua valendo para a integração pelo componente. Quando o componente passar a expô-lo, este guia será atualizado. Contrato do campo na Referência da API Web.

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

  1. Criar a sessão — seu backend chama POST /web/sessions com a x-api-key e recebe { token, expires_at }.
  2. Embutir o componente — sua página carrega o SDK da CDN e entrega o token ao <provvi-camera>.
  3. 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.
  4. Tratar erros — browser bloqueado, GPS, recaptura, sessão expirada: cada um com uma ação clara para o usuário.
  5. Receber o resultado — o SDK emite uploaded com { session_id, authenticated_jpeg_url } (sem webhook). A URL vem preenchida só sob ALWAYS e é temporária; sob NEVER sobra o session_id, e o sidecar do manifesto sai em GET /web/session-results/:token, pelo seu backend, logo após o uploaded (não garantido depois dos 30 minutos de validade da sessão). Você verifica o manifesto.
  6. 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

Seção intitulada “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

Seção intitulada “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 retém e serve o JPEG assinado (ALWAYS) ou não o retém (NEVER / PER_SESSION). Configuração da conta.
gps_mode Nível da verificação de localização, definido com a Provvi. Configuração da conta.
Seção intitulada “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