Passo 6 · Configuração da sua conta

Alguns comportamentos do Web SDK não vivem no seu código — eles são configurados na sua conta Provvi e valem para todas as sessões que você cria. Esta página lista cada ajuste, o efeito que ele tem no fluxo dos passos anteriores e o que você precisa pedir à Provvi.

Suas credenciais (x-api-key de backend e license-key de frontend) são emitidas no admin-console em admin.provvi.com.br. Os ajustes abaixo são feitos pela Provvi mediante solicitação — escreva ao seu contato ou abra um chamado.

Domínios autorizados (origin allowlist)

Sua license-key só é aceita nos domínios que você registrar previamente. É o que permite deixar a license key no frontend com segurança: ela está amarrada à origem (origin-scoping), não a um segredo.

Antes de ir ao ar, envie à Provvi a lista de domínios de onde o componente será servido — por exemplo app.seusite.com.br e vistoria.seusite.com.br. Inclua também os domínios de homologação e de desenvolvimento que você usa.

Domínio não registrado bloqueia a captura

Se o componente carregar a partir de uma origem que não está na sua allowlist, a validação da license falha com ORIGIN_NOT_ALLOWED e o usuário vê o erro LICENSE_INVALID (8002) no evento error — antes mesmo de abrir a câmera. Registre cada novo domínio antes de publicar nele.

Armazenamento do JPEG autenticado (store_asset_policy)

Por padrão, a Provvi opera em modo zero-knowledge: o JPEG autenticado não é retido nos nossos servidores e você recebe apenas o manifest_url (o sidecar do manifesto). O campo authenticated_jpeg_url — entregue no evento uploaded da captura — vem null nesse caso.

Se você precisa que a Provvi guarde e sirva o JPEG autenticado por você, peça para mudar a política. São três modos:

store_asset_policy (definido na sua licença)	authenticated_jpeg_url
NEVER (default, fail-closed)	null — só o manifest_url é entregue
ALWAYS	URL presigned do JPEG autenticado
PER_SESSION	null no Web SDK — sem opt-in por sessão (ver abaixo)

O armazenamento é derivado da sua licença (store_asset_policy, definido junto à Provvi) — não é um parâmetro do POST /web/sessions. ALWAYS e NEVER decidem direto. O modo PER_SESSION é um opt-in por sessão que o Web SDK não expõe (não há parâmetro de request no SDK puro); sob PER_SESSION, o Web SDK se comporta como NEVER. Se você precisa do JPEG autenticado, use ALWAYS. Se a política não estiver definida, o comportamento é NEVER por design (fail-closed).

Nota

Mesmo quando authenticated_jpeg_url vem null, a prova continua íntegra: o manifesto C2PA e a assinatura ICP-Brasil A1 estão embutidos no próprio JPEG que você recebeu no evento de captura, e o manifest_url serve como sidecar verificável. Veja como tratar o null no Passo 5 · Resultados.

Verificação de localização (gps_mode)

A Provvi cruza a localização reportada pelo dispositivo com o IP de origem e acompanha o deslocamento entre as fotos de uma mesma sessão. O quanto isso bloqueia uma captura depende do modo configurado na sua conta:

gps_mode	O que acontece	Captura rejeitada?
off	Localização não é verificada	Nunca
report_only	Localização é registrada nos resultados, mas não bloqueia	Nunca
enforce	Divergência GPS×IP acima de gps_max_delta_km (300 km), ou deslocamento acima de 500 m dentro da mesma sessão, ou localização não verificável	Sim — POST /web/ingest responde 422

Apenas o modo enforce produz os erros 422 de localização que você trata no Passo 4 · Erros.

Contas novas nascem em enforce — leia isto

Uma conta recém-criada começa em gps_mode = enforce. Ao mesmo tempo, se o usuário negar a permissão de localização no navegador, o componente não bloqueia — ele segue com a captura reportando coordenadas nulas (comportamento descrito no Passo 3 · Ciclo de captura). A validação acontece então no servidor, e uma captura legítima pode ser rejeitada com 422 — por exemplo, um usuário sem GPS, atrás de VPN, ou com IP muito distante da posição real.

Duas ações práticas:

1. Oriente o usuário a permitir a localização na sua UI antes de abrir a câmera — é a forma mais confiável de evitar 422 indevidos.
2. Se o seu caso de uso não depende de localização, peça à Provvi para mudar para report_only ou off. Você continua recebendo as coordenadas nos resultados sem bloquear ninguém.

Limites e prazos de validade

Estes limites e TTLs valem para toda conta. Trate-os no seu fluxo de retry e ao decidir quando renovar uma URL.

Limite / prazo	Valor
Sessões criadas por x-api-key	100 por hora — acima disso, POST /web/sessions responde 429
Recarregamentos da SPA por sessão	20 — acima disso, o componente recebe 429 ao buscar a sessão
Validade da sessão (TTL)	30 minutos após a criação
Validade da URL de upload	5 minutos
Validade dos resultados e do asset	7 dias

Cada captura assinada é contabilizada no volume do seu plano.

Asset expirou depois de 7 dias?

As URLs presigned de authenticated_jpeg_url e manifest_url valem 7 dias. Se você precisa acessar o asset depois disso, use GET /web/image/:session_id para gerar uma nova URL fresca — sem recriar a sessão. Detalhes no Passo 5 · Resultados.

Quantidade de fotos e rótulos — você orquestra

O Web SDK é câmera de uma foto por chamada — não há perfis. Você decide quantas fotos (chamando open() N vezes no mesmo token) e o rótulo de orientação de cada uma (via overlay: { label } no open()). Nada a configurar na conta para isso — ver Passo 1 · Criar a sessão.

O que pedir à Provvi — resumo

• Domínios autorizados — a lista de origens (produção, homologação, dev) de onde o componente será servido.
• store_asset_policy — NEVER (zero-knowledge, default), ALWAYS ou PER_SESSION.
• gps_mode — enforce (default), report_only ou off.

A garantia que a sua conta entrega

Independente da configuração acima, o tier do Web SDK é assinatura server-side ICP-Brasil A1 sobre os bytes recebidos — uma âncora de dissuasão de fraude (fraud deterrence). Não há proveniência de hardware do dispositivo (device-side): o Web SDK não é uma cadeia de prova com âncora de hardware. Para esse nível de garantia, use o SDK mobile (iOS/Android). Deixe isso claro para quem consome os seus laudos.

---

← Passo 5 · Resultados · Voltar ao início da jornada →