Relatórios

Os endpoints desta página atendem a aba Relatório, da tela Relatórios. Eles listam os relatórios disponíveis, geram um relatório e entregam o arquivo pronto. A geração é feita em segundo plano: a chamada inicial responde na hora, e o arquivo é buscado depois, com o token devolvido. Os totais e gráficos da aba Dashboard estão em Dashboard.

Endpoints

Método	Caminho	Descrição
GET	/comercial/reports	Lista os relatórios disponíveis.
GET	/comercial/reports/{id}	Inicia a geração do relatório {id}, ou envia por e-mail.
GET	/comercial/reports/status/{token}	Consulta o andamento de uma geração.
GET	/comercial/reports/download/{token}	Baixa o arquivo de uma geração concluída.
GET	/comercial/reports/courses	Lista de apoio: cursos.
GET	/comercial/reports/companies	Lista de apoio: filiais do cliente.
GET	/comercial/reports/customers	Lista de apoio: empresas clientes.
GET	/comercial/reports/modalities	Lista de apoio: modalidades.
GET	/comercial/reports/student-statuses	Lista de apoio: status de aluno.
GET	/comercial/reports/users	Lista de apoio: usuários.

Relatórios disponíveis

GET /comercial/reports

Lista os relatórios que podem ser gerados. A resposta é a lista direta, sem paginação. Cada item traz id, name e type. O campo type indica os formatos disponíveis para o relatório, pelo código 1 (PDF) e 2 (Excel).

Exemplo:

curl -X GET "https://api.pedagogo.app/comercial/reports" \
  -H "Authorization: Bearer <token-de-sessao>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

Os números de id correspondem aos relatórios da aba Relatório:

id	Relatório
2	Relatório de vendas por representante
3	Relatório de vendas por responsável
4	Relatório de vendas detalhado
5	Relatório de pagamentos
6	Relatório de alunos com débitos
7	Relatório detalhado de treinamentos à faturar
8	Protocolo de entrega de documentos detalhado
9	Protocolo de entrega de documentos
10	Declaração de conclusão de treinamento
11	Relatório de vencimento de treinamentos
12	Relatório de assinatura
13	Relatório de programação de treinamentos
14	Relatório de transporte de treinamentos
15	Relatório de despesas
16	Relatório de vendas detalhado com despesas

Gerar um relatório

GET /comercial/reports/{id}

Inicia a geração do relatório {id}. Os filtros são enviados como parâmetros de consulta na URL.

Parâmetros de URL

Parâmetro	Obrigatório	Descrição
id	Sim	Número do relatório, conforme a lista de relatórios.
to_email	Não	Qualquer valor envia o relatório por e-mail para o usuário logado, em vez de gerar o arquivo para download.
type	Não	Só para o relatório de assinatura: 1 para PDF (padrão) e 2 para Excel.
start_date	Não	Início do período dos treinamentos, no formato de data.
end_date	Não	Término do período dos treinamentos, no formato de data.
course_id	Não	Número do curso (id).
modality_id	Não	Número da modalidade (id).

Os demais filtros da aba Relatório, como empresa, status do aluno, responsável, representante, filial, contrato e períodos de turma e de prática, também são enviados como parâmetros de consulta. Os nomes exatos variam de um relatório para outro e não estão todos listados nesta página.

Resposta

• Sem to_email: 202, com o token da geração e o campo channel, usado pela atualização em tempo real. A integração deve acompanhar a geração pelo token, como descrito abaixo.
• Com to_email: 200, com a mensagem de que o relatório será enviado por e-mail. Não há token nesse caso.

Exemplo:

curl -G "https://api.pedagogo.app/comercial/reports/4" \
  -H "Authorization: Bearer <token-de-sessao>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data-urlencode "start_date=2026-01-01" \
  --data-urlencode "end_date=2026-03-31"

Acompanhar e baixar

A geração segue três passos: a chamada inicial enfileira o relatório, a consulta de status acompanha o andamento e o download entrega o arquivo quando ele estiver pronto.

GET /comercial/reports/status/{token}

Devolve o estado atual da geração. Faça a consulta em intervalos curtos, até o status virar ready ou failed.

Resposta

200, com os campos:

Campo	Descrição
status	pending (na fila), running (em andamento), ready (pronto para download) ou failed (falhou).
phase	Etapa atual da geração, como consulta, escrita ou conclusão.
message	Texto de andamento, para exibir ao usuário.
percentage	Progresso de 0 a 100.
download_name	Nome do arquivo para download. Vem preenchido quando o relatório está pronto.
error	Mensagem de falha. Vem preenchida quando status é failed.

Enquanto a geração não tiver registrado nenhum estado, a resposta é pending. O mesmo acontece com um token desconhecido ou expirado.

GET /comercial/reports/download/{token}

Baixa o arquivo do relatório pronto. Chame quando status for ready. A resposta é o arquivo, com o nome download_name.

• O arquivo fica disponível por 60 minutos depois que o relatório fica pronto.
• O download é de uso único: depois de baixado, o token deixa de valer.
• Se o token expirou, já foi baixado ou o relatório não está disponível, a resposta é 410, com {"message": "..."}. Gere o relatório de novo.

Listas auxiliares

Estas consultas alimentam os filtros da aba Relatório. Cada uma devolve a lista do cliente da sessão.

• courses: cursos. Use o id no filtro course_id.
• companies: filiais do cliente. Aparecem no filtro Filial, quando o cliente tem mais de uma.
• customers: empresas clientes, usadas no filtro Empresa.
• modalities: modalidades. Use o id no filtro modality_id.
• student-statuses: status de aluno, usados no filtro Status do aluno.
• users: usuários do cliente, usados nos filtros Responsável e Representante.