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

Momento	Comportamento
Primeiro uso	Validação obrigatória via rede
Dentro de 1 hora	Cache local, sem rede
Após 1 hora	Revalida via rede
Sem rede + cache < 24h	Grace period — usa cache expirado
Sem rede + cache > 24h	Bloqueio — LICENSE_NETWORK_ERROR

---

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
license_id	string	ID interno da licença (estável entre rotações)
client_id	string	UUID do cliente (usado internamente)
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

1. Cada captura incrementa o contador no backend
2. O SDK envia POST /usage/increment após cada captura bem-sucedida
3. Se o volume exceder o limite: próxima validação retorna VOLUME_EXCEEDED
4. O SDK invalida o cache local e bloqueia novas capturas

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 sem interrupção:

1. Admin rotaciona no console → nova chave gerada
2. Chave antiga continua válida por 1 captura (grace)
3. Integrador atualiza a chave no código/config
4. Nova chave passa a ser usada nas próximas validações

O license_id permanece estável entre rotações — o rastreamento de volume não é afetado.

---

Revogação

Revogar uma licença bloqueia imediatamente todas as capturas usando aquela chave:

1. Admin revoga no console
2. Próxima validação retorna { "valid": false, "reason": "REVOKED" }
3. SDK limpa cache e bloqueia
4. Alerta REVOKED emitido no Admin Console

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

---

Cache — detalhes por plataforma

Plataforma	Armazenamento	Chave do cache
Android	SharedPreferences	provvi_license_cache_{hashCode(licenseKey)}
iOS	UserDefaults	provvi_license_cache (Codable)
Web	Não persistido	Em memória durante a sessão do componente

Invalidação do cache

O cache é invalidado automaticamente quando:

• TTL de 1 hora expira
• Volume excedido é detectado
• SDK chama invalidateLicenseCache() / LicenseValidator.clearCache()
• Licença é rotacionada (novo hash da chave)

---

Obter suas credenciais

1. Acesse o Admin Console
2. Navegue até Clientes → Seu cliente
3. Na seção Licenças, copie a License Key (para o SDK)
4. 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