Central de Documentação

Guia do administrador

Governança mínima: organizações internas vs clientes externos, segurança, normas e relatórios controlados.

Última atualização: 30 de maio de 2026Impressão do browser (A4)

Guia de administrador

Este guia contém informações sensíveis de configuração de produção. Restrinja o acesso a operadores com role admin.

1. Variáveis de ambiente obrigatórias

Variável	Obrigatória	Notas
AUTH_SECRET_KEY	✅ Sim	≥32 chars, distinta do Fernet, não pode ser o default dev-insecure-*
FERNET_ENCRYPTION_KEY	✅ Sim	Base64 URL-safe 32 bytes. Protege chaves de API dos agentes.
POSTGRES_PASSWORD	✅ Sim	Não pode ser 'changeme'. Use gerador de senhas fortes.
ENVIRONMENT	✅ Sim	'production' — ativa todas as validações de segurança
VERIFICATION_PUBLIC_BASE	✅ Sim	URL pública da instância. Ex.: https://heillon-legal-ui.vercel.app
FORCE_STUB_TIMESTAMP	❌ Não	Deve ser 'false'. Nunca 'true' em produção.
TSA_PROVIDER	Opcional	certisign \| serpro \| freetsa (default: certisign)
MISSION_ROUTES_REQUIRE_AUTH	Opcional	true — exigir JWT em todas as rotas de missão (recomendado)
BILLING_WEBHOOK_SECRET	Opcional	HMAC-SHA256 do webhook de billing. Vazio = endpoint 503 (desativado). Defina em produção.
HEILLON_ADMIN_TOKEN	Opcional	Token dos endpoints /api/v1/admin/* (header X-Heillon-Admin-Token). ≥24 chars. Vazio = 503.
SENTRY_DSN	Opcional	Captura de erros (PII off). Vazio = SDK não inicializado. Recomendado em produção.
POSTMARK_SERVER_TOKEN	Opcional	E-mail transacional. Vazio = modo stub (apenas loga, não envia).

2. Deploy com Docker Compose

Stack completa — docker-compose up

# Definir variáveis obrigatórias
$env:AUTH_SECRET_KEY    = "sua-chave-jwt-segura-min-32-caracteres"
$env:FERNET_ENCRYPTION_KEY = "sua-chave-fernet-base64-32-bytes"
$env:POSTGRES_PASSWORD  = "senha-postgres-forte"
$env:VERIFICATION_PUBLIC_BASE = "https://sua-instancia.com"

# Subir stack
docker compose up -d

# Verificar saúde
curl http://localhost:8000/health

Ordem de inicialização

O backend aguarda PostgreSQL e Redis saudáveis antes de iniciar (healthcheck no docker-compose). Aguarde ~30s na primeira inicialização.

3. Gestão multi-tenant

Cada organização tem um organization_id único. O isolamento é garantido em duas camadas:

Aplicação — todas as queries filtram por organization_id
Base de dados — RLS (Row Level Security) no PostgreSQL/Supabase

Criar organização
O primeiro registro cria automaticamente a organização. Organizações adicionais requerem criação manual via admin.
Gerenciar usuários
Em /health (admin only), visualize e gerencie usuários da organização. Atribua roles: advogado (operador) ou admin.

4. Configurar agentes de IA

Acessar /agent-config
Requer autenticação com role admin.
Adicionar executor
Escolha o tipo (Ollama / OpenAI / Anthropic / Custom) e forneça a API key. A chave é encriptada imediatamente com Fernet.
Testar conectividade
Use o botão Testar para verificar a conexão antes de associar ao tenant.
Associar à organização
O executor fica disponível para todas as missões do tenant após associação.

5. Manutenção do corpus normativo

Dica

O corpus normativo deve ser atualizado quando há novas regulamentações relevantes para o seu setor jurídico. O motor FTS5 indexa automaticamente novas regras inseridas via API.

POST

/api/v1/normative/rules

Adicionar nova regra ao corpus normativo.

🔐 Auth

GET

/api/v1/normative/search?q=lgpd

Pesquisa FTS5 no corpus.

🔐 Auth

6. Health dashboard

A rota /health (admin only) mostra estado em tempo real: PostgreSQL, Redis, TSA provider, e métricas de utilização.

GET

/health

Liveness check — retorna 200 quando todos os serviços OK.

GET

/api/v1/health/detailed

Painel detalhado com estado de cada serviço.

🔐 Auth

7. Coletores e quota

Os coletores (Extensão e Gateway) autenticam-se por chave de API e respeitam a quota do tier da organização. Não há configuração de servidor por coletor além da chave: o usuário gera a sua em /conta/api-keys e acompanha o consumo em /conta/quota.

Tiers: Free (50 HDRs/mês, retenção 30d), Pro/Team/Enterprise (ilimitado, retenção e usuários crescentes).
Excedente: ao esgotar a quota, os coletores recebem HTTP 402 até a renovação do período.
Retenção: a purga por tier é executada pelo cron scripts/cron_purge_retention.py.

8. Webhook de billing (mudança de tier)

A contratação de planos vive no site institucional (fora do console). A mudança de tier chega ao backend por um webhook assinado com BILLING_WEBHOOK_SECRET(HMAC-SHA256 sobre o corpo bruto). Sem o segredo, o endpoint responde 503.

POST

/api/v1/billing/webhook

Eventos tier_changed / subscription_cancelled / payment_failed (HMAC obrigatório).

9. Painel admin do beta

Os endpoints /api/v1/admin/* expõem métricas agregadas do beta (sem PII) e são protegidos pelo header X-Heillon-Admin-Token (valor de HEILLON_ADMIN_TOKEN, distinto do JWT e das chaves de API). Sem token configurado, retornam 503.

10. Observabilidade e e-mail

Sentry (SENTRY_DSN) — captura de erros com send_default_pii=False; vazio desativa o SDK.
Postmark (POSTMARK_SERVER_TOKEN) — e-mail transacional; vazio opera em modo stub (apenas loga).
Caddy — TLS automático no deploy via Docker Compose (Caddyfile).

Central de Documentação

Guia do administrador

Governança mínima: organizações internas vs clientes externos, segurança, normas e relatórios controlados.

Última atualização: 30 de maio de 2026Impressão do browser (A4)

Guia de administrador

Este guia contém informações sensíveis de configuração de produção. Restrinja o acesso a operadores com role admin.

1. Variáveis de ambiente obrigatórias

Variável	Obrigatória	Notas
AUTH_SECRET_KEY	✅ Sim	≥32 chars, distinta do Fernet, não pode ser o default dev-insecure-*
FERNET_ENCRYPTION_KEY	✅ Sim	Base64 URL-safe 32 bytes. Protege chaves de API dos agentes.
POSTGRES_PASSWORD	✅ Sim	Não pode ser 'changeme'. Use gerador de senhas fortes.
ENVIRONMENT	✅ Sim	'production' — ativa todas as validações de segurança
VERIFICATION_PUBLIC_BASE	✅ Sim	URL pública da instância. Ex.: https://heillon-legal-ui.vercel.app
FORCE_STUB_TIMESTAMP	❌ Não	Deve ser 'false'. Nunca 'true' em produção.
TSA_PROVIDER	Opcional	certisign \| serpro \| freetsa (default: certisign)
MISSION_ROUTES_REQUIRE_AUTH	Opcional	true — exigir JWT em todas as rotas de missão (recomendado)
BILLING_WEBHOOK_SECRET	Opcional	HMAC-SHA256 do webhook de billing. Vazio = endpoint 503 (desativado). Defina em produção.
HEILLON_ADMIN_TOKEN	Opcional	Token dos endpoints /api/v1/admin/* (header X-Heillon-Admin-Token). ≥24 chars. Vazio = 503.
SENTRY_DSN	Opcional	Captura de erros (PII off). Vazio = SDK não inicializado. Recomendado em produção.
POSTMARK_SERVER_TOKEN	Opcional	E-mail transacional. Vazio = modo stub (apenas loga, não envia).

2. Deploy com Docker Compose

Stack completa — docker-compose up

# Definir variáveis obrigatórias
$env:AUTH_SECRET_KEY    = "sua-chave-jwt-segura-min-32-caracteres"
$env:FERNET_ENCRYPTION_KEY = "sua-chave-fernet-base64-32-bytes"
$env:POSTGRES_PASSWORD  = "senha-postgres-forte"
$env:VERIFICATION_PUBLIC_BASE = "https://sua-instancia.com"

# Subir stack
docker compose up -d

# Verificar saúde
curl http://localhost:8000/health

Ordem de inicialização

O backend aguarda PostgreSQL e Redis saudáveis antes de iniciar (healthcheck no docker-compose). Aguarde ~30s na primeira inicialização.

3. Gestão multi-tenant

Cada organização tem um organization_id único. O isolamento é garantido em duas camadas:

Aplicação — todas as queries filtram por organization_id
Base de dados — RLS (Row Level Security) no PostgreSQL/Supabase

Criar organização
O primeiro registro cria automaticamente a organização. Organizações adicionais requerem criação manual via admin.
Gerenciar usuários
Em /health (admin only), visualize e gerencie usuários da organização. Atribua roles: advogado (operador) ou admin.

4. Configurar agentes de IA

Acessar /agent-config
Requer autenticação com role admin.
Adicionar executor
Escolha o tipo (Ollama / OpenAI / Anthropic / Custom) e forneça a API key. A chave é encriptada imediatamente com Fernet.
Testar conectividade
Use o botão Testar para verificar a conexão antes de associar ao tenant.
Associar à organização
O executor fica disponível para todas as missões do tenant após associação.

5. Manutenção do corpus normativo

Dica

O corpus normativo deve ser atualizado quando há novas regulamentações relevantes para o seu setor jurídico. O motor FTS5 indexa automaticamente novas regras inseridas via API.

POST

/api/v1/normative/rules

Adicionar nova regra ao corpus normativo.

🔐 Auth

GET

/api/v1/normative/search?q=lgpd

Pesquisa FTS5 no corpus.

🔐 Auth

6. Health dashboard

A rota /health (admin only) mostra estado em tempo real: PostgreSQL, Redis, TSA provider, e métricas de utilização.

GET

/health

Liveness check — retorna 200 quando todos os serviços OK.

GET

/api/v1/health/detailed

Painel detalhado com estado de cada serviço.

🔐 Auth

7. Coletores e quota

Tiers: Free (50 HDRs/mês, retenção 30d), Pro/Team/Enterprise (ilimitado, retenção e usuários crescentes).
Excedente: ao esgotar a quota, os coletores recebem HTTP 402 até a renovação do período.
Retenção: a purga por tier é executada pelo cron scripts/cron_purge_retention.py.

8. Webhook de billing (mudança de tier)

POST

/api/v1/billing/webhook

Eventos tier_changed / subscription_cancelled / payment_failed (HMAC obrigatório).

9. Painel admin do beta

10. Observabilidade e e-mail

Sentry (SENTRY_DSN) — captura de erros com send_default_pii=False; vazio desativa o SDK.
Postmark (POSTMARK_SERVER_TOKEN) — e-mail transacional; vazio opera em modo stub (apenas loga).
Caddy — TLS automático no deploy via Docker Compose (Caddyfile).