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.
Somente servidor
A chave deve permanecer no backend da integração e nunca ser exposta no navegador.
Endpoints
Rotas Disponíveis
| Método | Rota | Uso |
|---|---|---|
| GET | /api/v1/health-analytics/external/status | Check de conectividade e validação da chave. |
| GET | /api/v1/health-analytics/external/contracts | Lista os contratos vinculados ao Tenant. |
| GET | /api/v1/health-analytics/external/contracts/:id/snapshot | Obtém o último snapshot analítico do contrato. |
| GET | /api/v1/health-analytics/external/contracts/:id/risk-score | Obtém o detalhamento do Risk Score do contrato. |
| GET | /api/v1/health-analytics/external/contracts/:id/benchmark | Retorna dados comparativos do contrato com o mercado. |
| GET | /api/v1/health-analytics/external/contracts/:id/recommendations | Consulta as sugestões automáticas baseadas em regras de IA. |
| GET | /api/v1/health-analytics/external/portfolio/alerts | Lista alertas ativos detectados em toda a carteira. |
| GET | /api/v1/health-analytics/external/market-trends | Retorna as tendências gerais e comportamento do mercado. |
Autenticação
Exemplo de Requisição
# A autenticação é aceita somente pelo header:
curl -H "X-API-Key: sua-chave" \
https://chatapi.omnitheus.com.br/analytics/api/v1/health-analytics/external/status
# URL base da API Externa v1:
https://chatapi.omnitheus.com.br/analytics/api/v1/health-analytics/external
Proteção de Tráfego
Limite Operacional
API externa300 req/min por IP
Ao exceder o limite, a API responde com 429 Too Many Requests e informa em Retry-After quantos segundos aguardar.
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 operacional de 300 requisições por minuto e por IP foi considerado.
Os códigos 401, 403, 404 e 429 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.