Pular para o conteúdo
GET/relatorios/volume

Volume de conversas e mensagens

relatorios:lerexporta CSV

Conversas novas e resolvidas e mensagens recebidas/enviadas no período, em uma linha por dia, semana ou mês, mais o movimento por hora do dia. Os mesmos números da tela Relatórios.

GET /relatorios/volume

curl "https://chat.forsi.com.br/api/v1/relatorios/volume?de=2026-09-01&ate=2026-09-30&granularidade=semana" \
  -H "Authorization: Bearer $FORSI_CHAVE"
Resposta 200 · JSON (com formato=csv, CSV)
{
  "dados": {
    "periodo": {
      "de": "2026-10-12",
      "ate": "2026-10-12",
      "dias": 30,
      "fuso": "America/Sao_Paulo",
      "granularidade": "dia",
      "caixa_id": "7a9d53e9-9d1b-4122-923b-fac67958f445"
    },
    "resumo": {
      "conversas_novas": 12,
      "conversas_resolvidas": 12,
      "mensagens_recebidas": 12,
      "mensagens_enviadas": 12,
      "mensagens_do_agente": 12,
      "notas_internas": 12
    },
    "por_hora": [
      {
        "hora": 9,
        "mensagens_recebidas": 12,
        "mensagens_enviadas": 12
      }
    ],
    "linhas": [
      {
        "inicio": "2026-10-12T17:00:00.000Z",
        "fim": "2026-10-12T17:30:00.000Z",
        "conversas_novas": 12,
        "conversas_resolvidas": 12,
        "mensagens_recebidas": 12,
        "mensagens_enviadas": 12,
        "mensagens_do_agente": 12,
        "notas_internas": 12
      }
    ]
  }
}

Parâmetros de consulta#

  • dedata AAAA-MM-DDopcional

    Primeiro dia (AAAA-MM-DD, no fuso da organização). Padrão: 29 dias antes de ate.

  • atedata AAAA-MM-DDopcional

    Último dia, inclusive. Padrão: hoje. O período vai até 366 dias.

  • granularidade"dia" | "semana" | "mes"opcional

    Tamanho de cada linha da série: dia (padrão), semana (começa na segunda) ou mes.

  • caixa_iduuidopcional

    Só os números desta caixa (WhatsApp, Instagram...). Veja as caixas em GET /me.

  • formato"json" | "csv"opcional

    json (padrão) ou csv (UTF-8 com BOM, separado por vírgula, pronto para planilha).

Resposta#

200 com {"dados": ...}: RelatorioVolume. Com formato=csv, um arquivo CSV.

  • periodoobjectopcional

    O período que valeu na consulta (com os padrões aplicados).

  • periodo.dedata AAAA-MM-DDopcional
    —
  • periodo.atedata AAAA-MM-DDopcional
    —
  • periodo.diasintegeropcional
    —
  • periodo.fusostringopcional
    • ex.: America/Sao_Paulo
  • periodo.granularidade"dia" | "semana" | "mes"opcional

    Só nos relatórios em série.

  • periodo.caixa_iduuidopcional
    —
  • resumoobjectopcional
    —
  • resumo.conversas_novasintegeropcional
    —
  • resumo.conversas_resolvidasintegeropcional
    —
  • resumo.mensagens_recebidasintegeropcional
    —
  • resumo.mensagens_enviadasintegeropcional
    —
  • resumo.mensagens_do_agenteintegeropcional

    Das enviadas, as que o agente de IA mandou.

  • resumo.notas_internasintegeropcional
    —
  • por_horalista de objectopcional

    24 itens, hora do dia no fuso da organização.

  • por_hora[].horaintegeropcional
    —
  • por_hora[].mensagens_recebidasintegeropcional
    —
  • por_hora[].mensagens_enviadasintegeropcional
    —
  • linhaslista de objectopcional

    Uma linha por dia, semana ou mês.

  • linhas[].iniciodata AAAA-MM-DDopcional
    —
  • linhas[].fimdata AAAA-MM-DDopcional

    Último dia da linha (nas pontas do período, a linha é cortada).

  • linhas[].conversas_novasintegeropcional
    —
  • linhas[].conversas_resolvidasintegeropcional
    —
  • linhas[].mensagens_recebidasintegeropcional
    —
  • linhas[].mensagens_enviadasintegeropcional
    —
  • linhas[].mensagens_do_agenteintegeropcional
    —
  • linhas[].notas_internasintegeropcional
    —

Erros#

Todo erro vem como {"erro": {"codigo", "mensagem"}}. Trate pelo codigo: ele não muda.

Status de erro desta operação
StatusQuando
401Chave ausente ou inválida (resposta igual para qualquer motivo).
403Plano sem API, escopo insuficiente ou https/origem recusados.
422Dados inválidos ou regra de negócio (ex.: janela_fechada; conta_restrita = a Meta restringiu a conta por spam: erro traz os campos de RestricaoMeta, como ate, escopo, motivo e retry_after_s).
429Limite de requisições. Veja Retry-After.
Códigos de erro que esta área pode devolver6
  • periodo_longoEscolha um período de até 366 dias.
  • periodo_invalidoPeríodo inválido: `de` precisa ser antes de `ate` (AAAA-MM-DD).
  • granularidade_invalidagranularidade deve ser dia, semana ou mes.
  • caixa_invalidaCaixa não encontrada nesta organização (veja GET /me).
  • limite_relatoriosRelatórios têm limite próprio, mais baixo. Espere o tempo de Retry-After.
  • relatorio_demorouO relatório demorou demais. Escolha um período menor ou uma granularidade maior (semana ou mes).

Os erros que valem para qualquer rota (chave, limite, JSON) estão em Erros.