> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thenewscc.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Relatórios e Métricas

> API completa para geração de relatórios avançados do SAC com cache de 2h

## Visão Geral

A API de relatórios do SAC fornece endpoints completos para análise de dados, métricas de performance, tendências e distribuição de tickets. Todos os endpoints de relatórios utilizam **cache KV com TTL de 2 horas** para otimização de performance.

### Características

* **Cache inteligente**: Respostas cacheadas por 2 horas no Cloudflare KV
* **Filtros avançados**: Data, categoria, issue, status, newsletter, agente
* **Agrupamento temporal**: Por hora, dia, semana, mês ou ano
* **Métricas de cache**: Headers indicam hit/miss e tempo de expiração

### Headers de Cache

Todas as respostas incluem informações sobre o cache:

```http theme={null}
X-Cache: HIT | MISS
X-Cache-Age: 300s
X-Cache-Expires-In: 7200s
```

## Endpoints Disponíveis

| Endpoint                                                            | Método | Descrição                               |
| ------------------------------------------------------------------- | ------ | --------------------------------------- |
| [/relatorios/dashboard](/api-reference/sac/reports-dashboard)       | GET    | Dashboard geral com métricas principais |
| [/relatorios/detalhado](/api-reference/sac/reports-detailed)        | POST   | Relatório completo com todos os filtros |
| [/relatorios/agentes](/api-reference/sac/reports-agents)            | GET    | Performance dos agentes                 |
| [/relatorios/issues](/api-reference/sac/reports-issues)             | GET    | Tendências de issues                    |
| [/relatorios/cohorts](/api-reference/sac/reports-cohorts)           | GET    | Análise de cohorts                      |
| [/relatorios/distribuicao](/api-reference/sac/reports-distribution) | GET    | Distribuição por hora/dia/newsletter    |
| [/relatorios/resumo](/api-reference/sac/reports-summary)            | GET    | Resumo rápido (últimos 30 dias)         |
| [/relatorios/comparativo](/api-reference/sac/reports-comparison)    | GET    | Comparativo entre períodos              |
| [/relatorios/serie-temporal](/api-reference/sac/reports-timeseries) | GET    | Série temporal de tickets               |
| [/relatorios/resolucao](/api-reference/sac/reports-resolution)      | GET    | Métricas de resolução                   |
| [/relatorios/filtros](/api-reference/sac/reports-filters)           | GET    | Filtros disponíveis                     |

## Filtros Comuns

A maioria dos endpoints aceita os seguintes filtros:

| Parâmetro     | Tipo   | Descrição                                |
| ------------- | ------ | ---------------------------------------- |
| `data_inicio` | string | Data de início (YYYY-MM-DD)              |
| `data_fim`    | string | Data de fim (YYYY-MM-DD)                 |
| `main`        | string | Categoria principal                      |
| `issue`       | string | Issue específico                         |
| `status`      | string | Status do ticket                         |
| `newsletter`  | string | Newsletter relacionada                   |
| `agente`      | string | Email do agente                          |
| `agrupar_por` | string | Agrupamento: hora, dia, semana, mes, ano |

## Categorias Principais

| Categoria                                         | Descrição                                       |
| ------------------------------------------------- | ----------------------------------------------- |
| `Programa de indicação e prêmios`                 | Dúvidas e problemas com o sistema de indicações |
| `Streak (pontuação diária)`                       | Issues relacionados ao sistema de streaks       |
| `Problemas de recebimento das edições e cadastro` | Problemas com entrega de newsletters            |

## Cache e Performance

### Configuração

* **TTL**: 2 horas (7200 segundos)
* **Storage**: Cloudflare KV
* **Timeout**: 100ms para operações de cache

### Invalidação Automática

O cache é invalidado quando:

* Um novo ticket é criado
* O status de um ticket é alterado
* Um ticket é deletado
* Uma mensagem é adicionada

## Autenticação

Todos os endpoints requerem autenticação via JWT:

```http theme={null}
Authorization: Bearer {token}
```