Relatório Comercial

Visão de gestão do atendimento: reúne em uma chamada os indicadores do período - chamados, atendimentos, lembretes, modelos de lembrete, obrigações, ranking de colaboradores e top clientes. O mesmo relatório pode ser exportado em CSV ou XLSX.

As duas rotas exigem perfil administrador, diretoria ou gestor (require_perfil); o perfil funcionário recebe 403. Veja Autenticação.

Base path

Todos os endpoints abaixo são montados sob o prefixo:

/api/v1/relatorio-comercial

A URL completa em produção é https://api.contabilidadealcance.com.br/api/v1/relatorio-comercial.

Escopos necessários

Escopo	Operações
`relatorio_comercial:read`	`GET /`, `GET /export`

O escopo é derivado da rota: o prefixo /relatorio-comercial vira o recurso relatorio_comercial (hífen → underscore) e o método GET vira read. Além do escopo, vale o gate de perfil acima.

Parâmetros comuns

As duas rotas recebem os mesmos filtros de query, validados antes de tocar o banco:

Parâmetro	Tipo	Local	Obrigatório	Descrição
`data_inicio`	`date`	query	sim	Início do período (inclusivo), `YYYY-MM-DD`.
`data_fim`	`date`	query	sim	Fim do período (inclusivo), `YYYY-MM-DD`.
`id_cliente`	`int`	query	não	Recorta por cliente (`> 0`).
`id_usuario`	`int`	query	não	Recorta por colaborador (`> 0`); cada seção usa a sua coluna.
`secoes`	`str`	query	não	Lista CSV de seções. Ausente = todas. Seção desconhecida → `422` (não é ignorada em silêncio).

Seções válidas: chamados, atendimentos, lembretes, modelos, obrigacoes, ranking_colaboradores, top_clientes.

Regras de período (422): data_inicio não pode ser posterior a data_fim; a janela máxima é de 366 dias entre as duas datas; data_fim precisa ser anterior a 31/12/9999.

Endpoints

`GET /relatorio-comercial/`

Gera o relatório do período, só com as seções pedidas.

Parâmetros

Os parâmetros comuns (seção acima).

Request

GET /api/v1/relatorio-comercial/?data_inicio=2026-09-01&data_fim=2026-09-30&secoes=ranking_colaboradores,top_clientes

Response 200 OK

{
  "status": "success",
  "message": "Relatório comercial gerado com sucesso",
  "data": {
    "periodo": { "data_inicio": "2026-09-01", "data_fim": "2026-09-30", "dias": 30 },
    "hoje": "2026-10-15",
    "filtros": { "id_cliente": null, "id_usuario": null },
    "secoes": {
      "ranking_colaboradores": [
        {
          "id_usuario": 7,
          "nome": "Maria Operadora",
          "atendimentos": 84,
          "chamados_concluidos": 31,
          "lembretes": 12,
          "tempo_medio_resolucao_horas": 5.4
        }
      ],
      "top_clientes": [
        {
          "id_cliente": 42,
          "razao_social": "Empresa Exemplo Ltda",
          "atendimentos": 9,
          "chamados": 4,
          "total": 13
        }
      ]
    }
  }
}

periodo.dias é inclusivo nas duas pontas. hoje é a data de referência (São Paulo) usada nas regras de atraso e vencimento. Escopo: relatorio_comercial:read + perfil administrador/diretoria/gestor

`GET /relatorio-comercial/export`

Exporta o mesmo relatório como arquivo, no formato longo Seção / Métrica / Valor / Quantidade.

Parâmetros

Os parâmetros comuns (seção acima), mais:

Parâmetro	Tipo	Local	Obrigatório	Descrição
`formato`	`str`	query	não	`csv` (padrão) ou `xlsx`. Outro valor → `422`.

Request

GET /api/v1/relatorio-comercial/export?data_inicio=2026-09-01&data_fim=2026-09-30&formato=xlsx

Response 200 OK

Arquivo binário (CSV ou XLSX) com Content-Disposition: attachment; filename="relatorio_comercial_<data_inicio>_<data_fim>.<csv|xlsx>". No XLSX a aba se chama Relatório Comercial.

Escopo: relatorio_comercial:read + perfil administrador/diretoria/gestor

Schemas

Seções de `data.secoes`

Só aparecem as seções pedidas em secoes (ou todas, sem o parâmetro). Distribuições com vocabulário fechado trazem todas as chaves, inclusive com zero.

Seção	Formato	Campos principais
`chamados`	objeto	`filtros_aplicados`, `abertos` (`total`, `por_status`, `por_tipo`), `concluidos` (`total`, `pela_equipe`, `pelo_cliente`, `tempo_medio_resolucao_horas`, `avaliacoes`, `nota_media`), `fila_atual` (contagem por status da fila + `sem_responsavel`)
`atendimentos`	objeto	`filtros_aplicados`, `total`, `por_canal`, `por_setor`, `por_quem_iniciou`, `por_servico_incluso`, `por_situacao`, `transferidos`, `retornos_em_atraso`, `top_palavras_chave` (`id`, `palavra`, `quantidade`)
`lembretes`	objeto	`filtros_aplicados`, `total`, `por_status`, `por_origem` (`manual`, `modelo`, `aniversario`, `obrigacao`)
`modelos`	objeto	`foto_atual` (sempre `true`), `filtros_aplicados`, `total`, `recorrencia_ativa`, `recorrencia_inativa`, `com_obrigacao_vinculada`, `por_tipo_recorrencia`, `por_departamento`
`obrigacoes`	objeto	`filtros_aplicados`, `total`, `entregues`, `entregues_no_prazo`, `entregues_com_atraso`, `pendentes_vencidas`, `pendentes_a_vencer`, `com_multa`, `por_status`, `por_departamento`
`ranking_colaboradores`	lista	`id_usuario`, `nome`, `atendimentos`, `chamados_concluidos`, `lembretes`, `tempo_medio_resolucao_horas`
`top_clientes`	lista	`id_cliente`, `razao_social`, `atendimentos`, `chamados`, `total`

Notas

Filtros por seção: filtros_aplicados diz quais filtros valem em cada seção. modelos é uma foto atual do catálogo e ignora período e filtros; obrigacoes respeita id_cliente, mas não id_usuario.
Limites internos de listas: o ranking traz até 20 colaboradores, o top de clientes até 10 e o top de palavras-chave até 10 (constantes em app/helpers/relatorio_comercial_helpers.py).