Licenciamento

Sistema de licenciamento, ambientes, controle de volume e cache.

Credenciais — distinção importante

Credencial	Formato	Local	Finalidade
API Key	`pvv_api_*`	Backend do integrador	Autenticar criação de sessões web (`POST /web/sessions`)
License Key	`pvv_<env>_<base58>`	Frontend / SDK	Validar licenciamento do SDK antes de cada captura
Token	UUID v4	Transitório	Identificar uma sessão de captura específica

A API Key é segredo de backend — expô-la no frontend permite que terceiros criem sessões na sua conta. A License Key é projetada para uso no frontend — o backend de licenciamento controla por volume de capturas e ambiente.

Ambientes

Cada licença pertence a um ambiente. O prefixo da chave identifica o ambiente:

Ambiente	Prefixo	Uso	Características
Sandbox	`pvv_sand_`	Desenvolvimento e testes	Volume ilimitado, integridade relaxada
Staging	`pvv_stag_`	Homologação	Volume limitado, integridade ativa
Production	`pvv_live_`	Produção	Volume limitado, integridade máxima

Chaves de ambientes diferentes não são intercambiáveis. Uma chave pvv_sand_ não funciona em produção.

Fluxo de validação

SDK (frontend/app)                    api.provvi.com.br
────────────────                      ──────────────────

1. POST /validate ──────────────────→ Verifica chave, contrato,
   { "license_key": "pvv_live_..." }   volume, status do cliente

                        ←──────────── { "valid": true,
                                        "environment": "PRODUCTION",
                                        "capture_resolution": "HD",
                                        ... }

2. SDK armazena em cache (1h)
3. Captura permitida

Quando a validação ocorre

No SDK Android:

Momento	Comportamento
Primeiro uso	Validação obrigatória via rede, dentro de `configure(...)`
Dentro de 1 hora desde a última validação	Cache local, sem rede
Após 1 hora	Revalida via rede na captura, antes de ela prosseguir
Sem rede (transitória)	O SDK tolera usando o último resultado de validação recente
Depois de uma falha de rede tolerada	O SDK pode seguir com o último resultado por até 1 hora desde a tentativa que falhou, sem voltar à rede, mesmo que a rede volte antes
Sem rede prolongada	Bloqueio — `LICENSE_NETWORK_ERROR`
Servidor de licenças responde sem veredito (erro HTTP, ou resposta de sucesso sem o veredito `valid`)	Bloqueio, sem tolerância — `LICENSE_VALIDATION_UNAVAILABLE`
A validação pela rede recusa a licença (revogada, expirada, volume excedido, cliente suspenso)	Bloqueio. O SDK apaga o resultado de validação que tinha guardado: sem rede, não há tolerância até uma nova validação bem-sucedida. Se o aparelho falhar ao apagar esse resultado, ele deixa de ser usado só no processo do app que recebeu a recusa, e enquanto esse processo durar
A política da licença muda durante uma captura	A captura é recusada uma vez — `LICENSE_POLICY_CHANGED_DURING_CAPTURE`; repita a captura

No Android, a tolerância vale só para falha de comunicação com o servidor de licenças: sem rede, tempo esgotado, ou uma resposta que não chega inteira e legível como resposta HTTP, que o SDK não distingue de uma queda de rede. Uma resposta do servidor sem veredito não usa o último resultado guardado. Em todos os casos, a tolerância só serve o resultado de uma validação bem-sucedida anterior, e nunca o conteúdo da resposta que falhou. Uma tentativa de validação pela rede desiste depois de cerca de 15 segundos, inclusive quando a resolução do nome do servidor demora, e conta como falha de rede.

No SDK iOS, a licença é validada dentro de configure(), com cache de 1 hora e tolerância sem rede, e a política validada ali vale até o próximo reset() seguido de configure(). As regras que decidem quando essa tolerância se aplica no iOS não são as do Android, descritas acima.

License Policy

A resposta de /validate retorna a policy que controla o comportamento do SDK:

Campo	Tipo	Descrição
`valid`	boolean	Se a licença é válida
`environment`	string	`PRODUCTION`, `STAGING`, `SANDBOX`
`integrity_enforcement`	string	Modo de aplicação da integridade
`capture_resolution`	string	Resolução máxima de captura
`tsa_required`	boolean	Se timestamp authority é obrigatório
`max_captures_per_session`	number?	Limite por sessão (null = ilimitado)
`captures_used`	number	Total de capturas no período atual
`volume_limit`	number	Limite mensal de capturas
`expires_at`	string	Data de expiração do contrato

Integrity Enforcement

Modo	Comportamento
`BLOCK`	Dispositivo comprometido → captura bloqueada
`WARN`	Dispositivo comprometido → captura prossegue, risco registrado
`IGNORE`	Verificação de integridade ignorada

Capture Resolution

Valor	Resolução	Megapixels
`SD`	1280 x 720	~0.9 MP
`HD`	1920 x 1080	~2.0 MP
`FHD`	2560 x 1440	~3.7 MP
`MAX`	Nativa do dispositivo	Variável

Controle de volume

O volume de capturas é rastreado mensalmente por licença.

Como funciona

Cada captura incrementa o contador no backend
Cada captura bem-sucedida é contabilizada no volume mensal da sua licença.
Se o volume exceder o limite: próxima validação retorna VOLUME_EXCEEDED
A partir dessa validação pela rede, o SDK bloqueia novas capturas (quando ela acontece está em Quando a validação ocorre, acima). No SDK Android, ao receber a recusa, o SDK apaga o resultado guardado e não segue sem rede até uma nova validação bem-sucedida; no SDK iOS, vale o que está em Revogação, abaixo

Alertas automáticos

O backend emite alertas nos seguintes thresholds:

Threshold	Alerta
70% do volume	`VOLUME_70` — aviso preventivo
90% do volume	`VOLUME_90` — ação recomendada
100% do volume	`VOLUME_100` — limite atingido

Os alertas aparecem no Admin Console e podem ser consultados via API.

Rotação de chaves

Chaves de licença podem ser rotacionadas no Admin Console:

Admin rotaciona no console → nova chave gerada, e a chave antiga passa a ser recusada pelo servidor de licenças (ver a nota abaixo)
Integrador atualiza a chave no código/config (ver Cache, abaixo)
Nova chave passa a ser usada nas próximas validações

Depois da rotação, o servidor de licenças recusa a chave antiga: a validação dela responde { "valid": false, "reason": "INVALID_KEY" }. Não conte com essa recusa no mesmo instante da rotação. Um app que ainda usa a chave antiga recebe a recusa numa validação da licença pela rede, e quando ela acontece depende da plataforma (ver Quando a validação ocorre e Revogação); antes disso, a captura também pode ser recusada por outro serviço da Provvi (ver Erros). Atualize os apps para a nova chave logo depois de rotacionar.

Revogação

Revogar uma licença faz o servidor recusar aquela chave em toda validação seguinte: o bloqueio definitivo da chave é do servidor. Do lado do SDK:

Admin revoga no console
A próxima validação pela rede retorna { "valid": false, "reason": "REVOKED" }
O SDK recusa a captura (no iOS, a recusa vem em configure())
Alerta REVOKED emitido no Admin Console

Quando essa validação pela rede acontece depende da plataforma (ver também Quando a validação ocorre, acima):

SDK Android: na primeira captura depois de 1 hora desde a validação anterior. Até lá, o SDK segue com o resultado guardado da última validação bem-sucedida, dentro de 1 hora desde ela, ou pela tolerância sem rede descrita ali. Isso não quer dizer que as capturas sigam: durante a captura, outros serviços da Provvi também conferem a chave e podem recusar a chave revogada antes dessa validação (ver Erros). Se uma tentativa pela rede falhou e o SDK seguiu pela tolerância, a tentativa seguinte pode esperar até 1 hora desde a que falhou, mesmo que a rede volte antes, e a recusa pela validação só chega nela. Ao receber a recusa pela rede, o SDK apaga o resultado guardado: a partir daí, sem rede, ele não segue capturando até uma nova validação bem-sucedida (com a ressalva de falha do aparelho ao apagar, em Quando a validação ocorre).
SDK iOS: a política validada em configure() não expira enquanto aquela configuração durar. A recusa chega no próximo configure() depois de reset(), quando ele valida pela rede (dentro de 1 hora desde a última validação, ele usa o resultado guardado, sem rede). Até lá, o SDK iOS segue com a política validada, e uma recusa não encurta a tolerância sem rede. Também aqui, isso não quer dizer que as capturas sigam: durante a captura, outros serviços da Provvi também conferem a chave e podem recusar a chave revogada antes dessa validação (ver Erros).

A revogação não pode ser desfeita. Para reativar, crie uma nova licença.

Cache

O cache é gerenciado internamente pelo SDK e fica ligado à chave de licença. Para trocar de ambiente (sandbox↔produção) ou de chave, chame reset() e depois configure(...) com a chave nova: o SDK não reaproveita o resultado guardado de uma chave para outra, e não há cache a limpar à mão.

Quando o cache deixa de valer

O resultado guardado deixa de ser usado sem ida à rede quando:

a última validação tem mais de 1 hora (sem rede, vale a tolerância descrita em Quando a validação ocorre);
a chave de licença muda, inclusive na rotação;
no SDK Android, a validação pela rede recusou a licença: o resultado guardado é apagado (com a ressalva de falha do aparelho ao apagar, em Quando a validação ocorre).

Uma recusa da licença (revogada, expirada, volume excedido, cliente suspenso) chega ao SDK na próxima validação pela rede. Antes dela, a captura também pode ser recusada por outro serviço da Provvi que recuse a chave (ver Erros).

Obter suas credenciais

Acesse o Admin Console
Navegue até Clientes → Seu cliente
Na seção Licenças, copie a License Key (para o SDK)
Na seção API Keys, crie uma API Key (para o backend)

Ambas as chaves são exibidas uma única vez ao serem criadas — armazene-as com segurança.

Ambientes de teste

Para desenvolvimento, use chaves pvv_sand_*:

Sem cobrança
Volume ilimitado
Integridade relaxada (jailbreak/root não bloqueia)
Mesmo fluxo funcional da produção