API Reference

Endpoints FastAPI documentados: autenticação, LGPD, parceiros, diagnóstico e health check.

Visão Geral

A API HestiaShield expõe endpoints REST para integração com parceiros, operações LGPD e monitoramento da plataforma.

Base URL: https://api.hestiashield.com.br
Versão: v1.0
Framework: FastAPI (Python 3.11) com Pydantic v2
Formato: JSON (application/json)
Auth B2B: API Key via header X-API-Key
Auth usuários: JWT Bearer via Keycloak

Rate Limits

Rota	Limite	Burst
/api/* (geral)	10 req/s	30
/auth/*	5 req/s	10
/lgpd/*	20 req/s	5

ℹ️

Todos os endpoints usam HTTPS. HTTP redireciona para HTTPS automaticamente (301). TLS 1.3 obrigatório.

Autenticação

Dois métodos de autenticação são suportados dependendo do tipo de cliente:

API Key (B2B)

Para parceiros e governo. Enviada via header HTTP.

X-API-Key: sk_live_xxxxxxxxxxxxxxxx

JWT Bearer (usuários)

Obtido via Keycloak OAuth2. Para acesso ao dashboard.

Authorization: Bearer <token>

Exemplo de requisição com API Key

POST /parceiros/interesse HTTP/1.1
Host: api.hestiashield.com.br
X-API-Key: sk_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "nome_empresa": "Telecom Brasil",
  "email": "parceiro@empresa.com.br",
  "tipo_parceiro": "telecom"
}

Erros de autenticação

401 — API key ausente ou inválida
403 — IP não whitelistado ou permissão insuficiente
429 — Rate limit excedido — verifique o header Retry-After

Endpoints

Todos os endpoints retornam JSON. Campos opcionais omitidos na requisição são ignorados com segurança.

Parceiros

POST /parceiros/interesse

Registra interesse de parceiro a partir do formulário do portal Partners.

Request Body

{
  "nome_empresa": "string",         // obrigatório
  "email": "string",                // obrigatório
  "telefone": "string",             // opcional
  "tipo_parceiro": "telecom|seguradora|saude|banco|farmacia|governo",
  "mensagem": "string",             // opcional
  "tipo_plano": "string"            // opcional
}

Response 200

{"status": "ok", "mensagem": "Interesse registrado com sucesso"}

Auth: nenhuma (público)

GET /parceiros/status

Verifica status da integração do parceiro autenticado.

Response 200

{"parceiro_id": "...", "status": "ativo", "plano": "business", "requests_hoje": 142}

Auth: API Key obrigatória

LGPD

POST /lgpd/solicitacao

Registra solicitação de direito do titular (Art. 18 LGPD).

Request Body

{
  "nome": "string",                 // obrigatório
  "email": "string",                // obrigatório
  "cpf": "string",                  // opcional
  "tipo_solicitacao": "acesso|correcao|exclusao|portabilidade|bloqueio|revogacao",
  "descricao": "string"             // obrigatório
}

Response 200

{"protocolo": "LGPD-2026-XXXX", "prazo_dias": 15, "email_confirmacao": true}

Auth: nenhuma (público)

GET /lgpd/status/{protocolo}

Verifica status de uma solicitação LGPD por número de protocolo.

Response 200

{"protocolo": "LGPD-2026-XXXX", "status": "em_andamento", "previsao": "2026-03-28"}

Auth: nenhuma (público)

Diagnóstico

POST /dispositivos/diagnostico

Registra resultado de diagnóstico de push notifications do app móvel.

Request Body

{
  "device_id": "string",
  "fcm_token": "string",
  "push_status": { /* objeto com estágios P1–P8 */ },
  "timestamp_iso": "string"         // ISO 8601
}

Response 200

{"status": "registrado"}

Auth: JWT Bearer (app autenticado)

Health

GET /health

Health check público — verifica disponibilidade da API.

Response 200

{"status": "ok", "version": "1.0.0", "timestamp": "2026-03-13T..."}

Auth: nenhuma

GET /health/deep

Health check detalhado — verifica DB, cache e serviços internos.

Response 200

{"status": "ok", "db": "ok", "keycloak": "ok", "uptime_s": 86400}

Auth: API Key (privado)

Webhooks

O HestiaShield envia requisições POST para a URL registrada pelo parceiro quando eventos relevantes ocorrem. O payload é JSON e sempre inclui um header de assinatura para verificação de autenticidade.

Verificação de assinatura

Cada requisição de webhook inclui o header X-HestiaShield-Signature: sha256=<HMAC>. Valide usando o segredo compartilhado fornecido no momento do cadastro:

import hmac, hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Eventos disponíveis

Evento	Descrição	Plano mínimo
alerta.criado	Novo alerta de risco detectado	Todos os planos
alerta.resolvido	Alerta marcado como resolvido	Business+
dispositivo.registrado	Novo dispositivo vinculado	Business+
dispositivo.desativado	Dispositivo desvinculado	Business+
lgpd.solicitacao	Solicitação LGPD recebida	Enterprise

Política de reenvio

Em caso de falha (timeout ou status >= 400), o HestiaShield realiza até 3 tentativas com backoff exponencial: 1s → 10s → 60s. Cada tentativa tem timeout de 5s. Após 3 falhas consecutivas, o webhook é desativado e o parceiro é notificado por e-mail.

⚠️

Idempotência: seu endpoint deve ser idempotente — o mesmo evento pode ser entregue mais de uma vez em caso de falha de rede. Use o campo event_id do payload para deduplicação.

Códigos de Erro

Todos os erros retornam JSON no formato {"detail": "mensagem de erro"} com o HTTP status code correspondente.

Código	Significado	Ação recomendada
400	Request inválida (campo faltando ou formato errado)	Verificar payload contra o schema documentado acima
401	API key ausente ou inválida	Verificar header `X-API-Key` e validade da chave
403	IP não autorizado ou permissão insuficiente	Solicitar whitelist do IP via faleconosco@hestiashield.com.br
404	Recurso não encontrado	Verificar path e ID do recurso
429	Rate limit excedido	Aguardar valor do header `Retry-After` (em segundos)
500	Erro interno	Verificar status.hestiashield.com.br; reportar se persistir
503	Serviço temporariamente indisponível	Aguardar e implementar retry com backoff exponencial

✅

Monitoramento: acompanhe a disponibilidade da API em tempo real em status.hestiashield.com.br. Incidentes e janelas de manutenção são publicados lá com antecedência.

← Anterior Produto Próximo → Changelog