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. Numa origem que ainda não passou pelo onboarding, a mesma causa pode chegar como LICENSE_NETWORK_ERROR (8003): trate os dois como “domínio ainda não habilitado”. Registre cada novo domínio antes de publicar nele.

O domínio é conferido em três momentos do fluxo — os dois últimos passaram a valer em 2026-09-18 —, e cada um chega ao seu código de um jeito:

Momento	O que o seu código recebe	O que fazer
Validação da licença (ao abrir a câmera)	LICENSE_INVALID (8002) com error.details.reason = ORIGIN_NOT_ALLOWED — ou, numa origem que nunca passou pelo onboarding, LICENSE_NETWORK_ERROR (8003)	Registre o domínio com a Provvi. Não repita em laço: a captura não passa enquanto o domínio não for habilitado.
Carregamento da sessão	SESSION_FETCH_FAILED (4001) com error.details.status = 403; o corpo traz block_reason web_origin_not_allowed ou web_origin_allowlist_empty (este quando a licença ainda não tem domínio algum registrado)	Mesma ação: registre o domínio. Não recrie sessões em laço — cada sessão nova conta no limite de criação (100 por hora, abaixo) e uma sessão nova também será recusada até o domínio ser habilitado: a autorização é da licença, não da sessão. A sessão continua válida: habilitado o domínio, a mesma sessão pode ser carregada de novo.
Envio da captura	INGEST_FAILED (4002) com error.details.status = 403 e os mesmos block_reason; se a sessão foi carregada em um domínio e enviada de outro, o block_reason é web_origin_session_mismatch	Domínio não habilitado ⇒ fale com a Provvi; a sessão continua válida e, habilitado o domínio, pode ser carregada de novo. web_origin_session_mismatch ⇒ o vínculo é definido no carregamento e não muda: conclua a captura na mesma página em que a sessão foi aberta, ou crie uma sessão nova e abra-a já nessa página.

Os corpos literais de cada caso estão no Passo 4 · Erros.

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. Nesse caso o evento uploaded da captura entrega authenticated_jpeg_url: null e nenhum manifest_url é entregue ao seu código (ele viaja na resposta HTTP do ingest, mas o componente não o expõe no evento). O sidecar do manifesto fica disponível ao seu backend em GET /web/session-results/:token — busque e guarde o manifest_url logo após o uploaded: o registro da sessão vale 30 minutos e a rota não é garantida depois disso (ver Referência da API Web).

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 — o evento traz só o session_id; o sidecar do manifesto sai por GET /web/session-results/:token, que você busca logo após o uploaded (não garantida depois dos 30 minutos de validade da sessão)
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 da assinatura existe: a Provvi assinou o JPEG e guardou o manifesto C2PA + assinatura ICP-Brasil A1 como sidecar, que o seu backend obtém em GET /web/session-results/:token logo após o uploaded. O componente não entrega o JPEG nem o manifesto no evento sob NEVER. E o JPEG autenticado não fica com ninguém: o componente não devolve os bytes e a Provvi não os retém.

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 — sob NEVER essa é a única cópia, e a Provvi continua sem retê-la. O componente <provvi-camera> publicado não expõe esse campo ao seu código: o parágrafo acima continua valendo para a integração pelo componente. Quando o componente passar a expô-lo, esta página será atualizada. Contrato do campo na Referência da API Web.

O que a Provvi retém em qualquer política: a imagem enviada pelo navegador passa por um armazenamento temporário só para ser assinada; ela não é a prova e não é servida a ninguém. Desde 2026-09-18, assim que a imagem é conferida contra o hash que o navegador enviou, ela é apagada do armazenamento temporário — ainda dentro da mesma captura, antes da assinatura. Uma varredura automática do provedor de nuvem (diária, sem hora exata garantida) continua valendo como rede: é ela que responde pelos casos em que a captura não chega a ser aceita (frames de câmera ao vivo reprovados, hash divergente, captura abandonada, e a foto recusada por tamanho antes de ser lida) ou em que a remoção falha — nesses casos o arquivo fica no armazenamento temporário por até cerca de um dia. Ou seja: é apagada na hora a imagem da captura aceita e a da foto recusada por tamanho depois de ser lida; espera a varredura a dos casos entre parênteses acima.

Se o seu laudo precisa exibir a imagem, use ALWAYS. Veja como tratar o null no Passo 5 · Resultados.

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

A Provvi valida a localização reportada pelo dispositivo. O nível dessa verificação é configurado por conta (gps_mode) e definido com a Provvi; os critérios da validação não são publicados. Uma captura que não passa na validação pode ser recusada com 422 (Passo 4 · Erros).

Oriente o usuário a permitir a localização

Se o usuário negar a permissão de localização no navegador, o componente não bloqueia — ele segue com a captura (comportamento descrito no Passo 3 · Ciclo de captura), e a validação acontece no servidor: uma captura legítima pode ser recusada com 422.

Duas ações práticas:

1. Antecipe a localização: chame camera.warmUpLocation() ao carregar a página (o pedido de permissão e o aquecimento do GPS acontecem antes de o usuário chegar ao botão) e reaja ao evento location — em denied, oriente o usuário; ou peça a permissão de localização na sua UI antes de abrir a câmera (Passo 3).
2. Se o seu caso de uso não depende de localização, fale com a Provvi sobre o nível de verificação de localização da sua conta. Você continua recebendo as coordenadas nos resultados.

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
Carregamentos da sessão (contando o primeiro)	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 das URLs presigned (JPEG e manifesto)	7 dias — o registro da sessão, consultável em GET /web/session-results/:token, não é garantido depois dos 30 minutos acima

Cada captura assinada é contabilizada no volume do seu plano.

Asset expirou depois de 7 dias?

As URLs presigned valem 7 dias. Para o JPEG autenticado (contas ALWAYS), gere uma nova com GET /web/image/:session_id — sem recriar a sessão. Para o manifesto não há renovação: baixe-o e guarde no seu storage ao receber o uploaded. 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 (uma sessão e um token por foto: cada token vale por uma captura bem-sucedida) 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 — nível da verificação de localização, definido com a Provvi.

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 →