# Relatórios e métricas (/docs/crm/relatorios)





O relatório de gestão entrega, **já agregadas**, as métricas que você veria num dashboard de atendimento: quantas conversas entraram, quantas a empresa iniciou, quantas foram resolvidas, quanto tempo a equipe leva para dar a primeira resposta e o quanto cada atendente produziu. Tudo num único endpoint — você **não reimplementa** a heurística no seu lado.

* **Endpoint:** [`GET /v1/inbox/reports/summary`](/docs/api/relatorios/getReportsSummary)
* **No painel:** Gestão → Relatórios.

## A janela de tempo [#a-janela-de-tempo]

A janela é definida por **datas no formato `YYYY-MM-DD`**, interpretadas no **fuso de Brasília (UTC−3)**:

| Parâmetro | Significado                                                    |
| --------- | -------------------------------------------------------------- |
| `from`    | Início da janela (inclusivo). Omitido = 29 dias antes de `to`. |
| `to`      | Fim da janela — inclui **o dia inteiro**. Omitido = hoje.      |

O padrão (sem `from`/`to`) são os **últimos 30 dias**. A janela máxima é de **366 dias**; pedidos maiores são recortados. A resposta **ecoa** a janela efetiva em `range`, então você sempre sabe o intervalo exato que foi medido.

<Callout type="info">
  As datas são do **fuso de Brasília**, mas os timestamps das conversas são
  gravados em UTC — a conversão é feita no servidor. Um relatório de
  `from=2026-06-01&to=2026-06-01` cobre o dia 1º de junho inteiro no horário de
  Brasília (de 00:00 a 23:59:59 BRT).
</Callout>

## Filtros [#filtros]

| Parâmetro        | Efeito                                                           |
| ---------------- | ---------------------------------------------------------------- |
| `instanceId`     | Restringe a uma instância (número). Vazio = todas.               |
| `assignedUserId` | Restringe às conversas atribuídas a um atendente. Vazio = todos. |

Os filtros se aplicam aos cards e às séries; a produtividade `porAtendente` ignora `assignedUserId` (ela já é quebrada por atendente).

## O modelo de dados da resposta [#o-modelo-de-dados-da-resposta]

```json
{
  "range": { "from": "2026-05-08", "to": "2026-06-06" },
  "total": 120,
  "receptivos": 80,
  "ativos": 40,
  "pendentes": 5,
  "abertas": 12,
  "resolvidas": 103,
  "novosContatos": 34,
  "atendentes": { "total": 4 },
  "primeiraResposta": {
    "mediaSegundos": 210,
    "medianaSegundos": 150,
    "amostras": 95
  },
  "porAtendente": [
    { "userId": "usr_01HV...", "nome": "Ana", "email": "ana@empresa.com", "total": 40, "resolvidas": 35 }
  ],
  "porDia": [
    { "dia": "2026-06-01", "abertas": 7 }
  ]
}
```

### Os cards [#os-cards]

| Campo              | O que conta                                                               |
| ------------------ | ------------------------------------------------------------------------- |
| `total`            | Total de conversas **abertas na janela** (todas as iniciadas no período). |
| `receptivos`       | Conversas **receptivas**: o **contato** mandou a primeira mensagem.       |
| `ativos`           | Conversas **ativas**: a **empresa** iniciou o contato.                    |
| `pendentes`        | Conversas em status `pending` na janela.                                  |
| `abertas`          | Conversas em status `open` na janela.                                     |
| `resolvidas`       | Conversas marcadas como `resolved` na janela.                             |
| `novosContatos`    | Contatos criados (primeiro contato de sempre) na janela.                  |
| `atendentes.total` | Número de atendentes do Projeto.                                          |

<Callout type="info">
  **Receptivo×ativo** sai da **direção de abertura** da conversa: quem enviou a
  primeira mensagem. Se foi o contato, a conversa é *receptiva*; se foi a sua
  equipe (envio ativo, campanha, primeira mensagem pelo painel/API), é *ativa*.
  `receptivos + ativos` cobre o `total`.
</Callout>

### Tempo de primeira resposta [#tempo-de-primeira-resposta]

O bloco `primeiraResposta` mede, **em segundos**, o intervalo entre a primeira mensagem **recebida** numa conversa e a primeira **resposta** da equipe:

| Campo             | Significado                                                             |
| ----------------- | ----------------------------------------------------------------------- |
| `mediaSegundos`   | Média aritmética do tempo de 1ª resposta.                               |
| `medianaSegundos` | Mediana (menos sensível a outliers — um caso muito lento não distorce). |
| `amostras`        | Quantas conversas tinham uma 1ª resposta para entrar no cálculo.        |

Use a **mediana** como indicador principal de SLA: ela representa o atendimento "típico". A média ajuda a detectar caudas longas (poucas conversas muito demoradas puxam a média para cima sem mexer na mediana). `amostras` diz o tamanho da base — uma mediana sobre 3 conversas não é representativa.

### Produtividade por atendente [#produtividade-por-atendente]

`porAtendente` é uma lista, uma entrada por atendente que teve conversas na janela:

| Campo            | Significado                                       |
| ---------------- | ------------------------------------------------- |
| `userId`         | Id do atendente (`null` para conversas sem dono). |
| `nome` / `email` | Identificação do atendente.                       |
| `total`          | Conversas atribuídas a ele na janela.             |
| `resolvidas`     | Quantas dessas ele resolveu.                      |

Conversas **sem atendente** aparecem agregadas numa entrada com `userId: null` — é a sua fila não distribuída.

### Série diária [#série-diária]

`porDia` é a série para o gráfico de linha/coluna: uma entrada por dia da janela, com `dia` (`YYYY-MM-DD`) e `abertas` (conversas iniciadas naquele dia). Dias sem movimento podem não aparecer — trate ausência como zero ao plotar.

## Exemplo [#exemplo]

```bash
curl "https://api.pepinozap.com.br/v1/inbox/reports/summary?from=2026-06-01&to=2026-06-06" \
  -H "Authorization: Bearer pzk_live_xxxxxxxxxxxxxxxx"

# Filtrando por um número e um atendente:
curl "https://api.pepinozap.com.br/v1/inbox/reports/summary?instanceId=inst_01HV...&assignedUserId=usr_01HV..." \
  -H "Authorization: Bearer pzk_live_xxxxxxxxxxxxxxxx"
```

<Callout type="warn">
  O relatório é uma **fotografia do estado atual** das conversas na janela:
  `resolvidas`, `pendentes` e `abertas` refletem o status **agora**, não no fim
  do período. Para histórico imutável, persista os números do seu lado a cada
  fechamento de período.
</Callout>