X-API-Key
Header obrigatório para autenticação das requisições.
API Externa v1
API Externa e Integrações.
A API Externa da plataforma fornece acesso programático seguro a dados estruturados de sinistros, análises de risco e benchmarking de forma que outros sistemas possam se conectar e consumir a inteligência do Harper Analytics.
analytics:read
Escopo necessário para leitura de dados de contratos, risk score e benchmarking.
api-keys.manage
Permissão administrativa para emissão e revogação de tokens.
Endpoints
Rotas Disponíveis
| Método | Rota | Uso |
|---|---|---|
| GET | /api/v1/health-analytics/status | Check de conectividade e validação da chave. |
| GET | /api/v1/health-analytics/contracts | Lista os contratos vinculados ao Tenant. |
| GET | /api/v1/health-analytics/contracts/:id/snapshot | Obtém o último snapshot analítico do contrato. |
| GET | /api/v1/health-analytics/contracts/:id/risk-score | Obtém o detalhamento do Risk Score do contrato. |
| GET | /api/v1/health-analytics/contracts/:id/benchmark | Retorna dados comparativos do contrato com o mercado. |
| GET | /api/v1/health-analytics/contracts/:id/recommendations | Consulta as sugestões automáticas baseadas em regras de IA. |
| GET | /api/v1/health-analytics/portfolio/alerts | Lista alertas ativos detectados em toda a carteira. |
| GET | /api/v1/health-analytics/market-trends | Retorna as tendências gerais e comportamento do mercado. |
Autenticação
Exemplo de Requisição
# Passando chave via Header:
curl -H "X-API-Key: sua-chave" \
https://api.harper.com/api/v1/health-analytics/status
# Passando chave via Query Param:
GET https://api.harper.com/api/v1/health-analytics/status?api_key=sua-chave
Políticas de Rate Limit
Limites de Requisição
Plano Padrão (Standard)1.000 req/hora
Plano Profissional10.000 req/hora
Plano CorporativoSob Demanda
O sistema retorna informações sobre o limite atualizado através dos cabeçalhos X-RateLimit-Limit e X-RateLimit-Remaining.
Checklist de Integração
Validações Técnicas
A chave de API foi gerada com o escopo 'analytics:read' habilitado.
As requisições externas incluem o cabeçalho 'X-API-Key' com valor correto.
O limite de requisições do plano contratado foi validado nos headers de resposta.
Os códigos de tratamento de erro (401 Unauthorized, 403 Forbidden) foram previstos na integração.
As chamadas de API estão isoladas em ambiente seguro e sem exposição de chaves no front-end público.