Relatórios e métricas

O modelo de dados do relatório de gestão do PEPINO ZAP — total de atendimentos, receptivo×ativo, abertas/pendentes/resolvidas, tempo de primeira resposta, novos contatos e produtividade por atendente. Como a janela de datas funciona (fuso de Brasília), os filtros e o formato exato da resposta.

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
No painel: Gestão → Relatórios.

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.

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).

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

{
  "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

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.

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.

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

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

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

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"

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.

On this page