Turmas

Turma é o agrupamento de alunos de um curso, com datas, carga horária, local e situação. Esta página reúne os endpoints da turma em si: listagem, detalhe, criação, alteração, exclusão, ações, exportação e importação de alunos. As demais partes da turma têm páginas próprias: alunos, instrutores, arquivos, auditorias e despesas.

No manual de usuário, esta área é a tela Turmas (módulo Operacional).

As regras gerais (cabeçalhos, paginação, erros) estão em Convenções. A obtenção do token de sessão está em Autenticação.

Endpoints

Método	Caminho	Descrição
GET	/operational/classes	Lista as turmas, com filtros e paginação
POST	/operational/classes	Cria uma turma
GET	/operational/classes/{uuid}	Consulta uma turma
PUT	/operational/classes/{uuid}	Altera uma turma
DELETE	/operational/classes/{uuid}	Apaga uma turma sem alunos
GET	/operational/classes/{uuid}/actions	Lista as ações disponíveis para a turma, com o checklist de cancelamento e conclusão
GET	/operational/classes/export/{class_uuid?}	Exporta as turmas para Excel
GET	/operational/classes/import-template	Baixa o modelo de planilha para importação de alunos
POST	/operational/classes/{uuid}/import-students	Importa alunos para a turma a partir de planilha

Lookups usados na turma

Estes endpoints alimentam os filtros da listagem e os formulários da turma. Os identificadores são os informados na resposta de cada lookup.

Método	Caminho	Descrição
GET	/operational/classes/modalities	Modalidades de treinamento
GET	/operational/classes/courses	Cursos
GET	/operational/classes/locations	Locais de treinamento
GET	/operational/classes/business	Empresas (clientes) ativas, usadas como empresa da turma
GET	/operational/classes/business/{customer_vendor_uuid}/cost-centers	Centros de custo de uma empresa

Listar turmas

GET /operational/classes

Lista as turmas da empresa cliente do usuário. Cada item traz os dados da turma e, em colunas próprias, o nome e o uuid do curso, da modalidade, do local e da empresa, a situação, a quantidade de alunos e o nome dos usuários que criaram e alteraram o registro.

Parâmetros de URL

Parâmetro	Descrição
search	Texto livre: busca no código da turma, nos comentários, no código, nome e sigla do curso e nos dados de alunos e empresas vinculados
code	Código da turma (valor exato)
status_id	Situação da turma (identificador da situação)
course_uuid	Curso (uuid, obtido em /operational/classes/courses)
modality_uuid	Modalidade (uuid, obtido em /operational/classes/modalities)
company_uuid	Empresa da turma (uuid)
customer_vendor_business_id	Empresa da turma (identificador numérico)
start_date	Com end_date, turmas que começam e terminam dentro do intervalo. Sem end_date, turmas que começam nesta data
end_date	Com start_date, turmas que começam e terminam dentro do intervalo. Sem start_date, turmas que terminam nesta data
per_page	Quantidade por página. Se omitido, a lista vem completa
page	Número da página, com per_page
column	Coluna de ordenação, com order
order	Sentido da ordenação: asc ou desc, com column

Sem ordenação informada, a lista vem da data de início mais recente para a mais antiga.

Resposta

• 200: lista de turmas ou, com per_page, objeto paginado (veja Convenções).

Campos principais de cada turma: uuid, code, start_date, end_date, daily_workload, workload, weekend_day, vacancies, comments, status_id, status_name, period, course_uuid, course_name, course_code, modality_uuid, modality_name, location_uuid, location_name, company_uuid, company_name, business_name, student_count, user_create_name, user_update_name, created_at e updated_at.

Exemplo

curl "https://api.pedagogo.app/operational/classes?search=Curso%20exemplo&per_page=15&page=1" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <token-de-sessao>"

Criar turma

POST /operational/classes

Cria uma turma. A API gera o código da turma (sequencial da empresa cliente), copia a carga horária do curso e registra na auditoria da turma a ação de criação.

Corpo

Campo	Obrigatório	Tipo	Descrição
company_uuid	Não	uuid	Empresa do treinamento (cadastro de empresas)
course_uuid	Sim	uuid	Curso da turma
modality_uuid	Sim	uuid	Modalidade da turma
period_id	Sim	inteiro	Período da turma (identificador do período)
weekend_day	Não	inteiro	Dia do fim de semana usado no cálculo das datas
daily_workload	Sim	inteiro	Carga horária diária, em horas
start_date	Sim	data	Data de início
end_date	Sim	data	Data de término, igual ou posterior à data de início
vacancies	Não	inteiro	Número de vagas
location_uuid	Não	uuid	Local de treinamento
status_id	Não	inteiro	Situação da turma (identificador da situação)

Resposta

• 201: a turma criada, com o uuid do novo registro.
• 422: dados inválidos, com a lista de erros por campo.

Exemplo

curl -X POST https://api.pedagogo.app/operational/classes \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token-de-sessao>" \
  -d '{
    "course_uuid": "<uuid-do-curso>",
    "modality_uuid": "<uuid-da-modalidade>",
    "period_id": 1,
    "daily_workload": 8,
    "start_date": "2026-12-01",
    "end_date": "2026-12-05",
    "vacancies": 20,
    "location_uuid": "<uuid-do-local>"
  }'

Consultar, alterar e apagar

GET /operational/classes/{uuid}

Devolve a turma informada, com o curso (e seus credenciamentos), a situação, a empresa, a modalidade e students_count, a quantidade de alunos.

• 200: a turma.
• 404: turma não encontrada, ou de outra empresa cliente.

PUT /operational/classes/{uuid}

Altera a turma. Os campos e as regras são os mesmos da criação, e todos os obrigatórios devem ser enviados. Se a data de início ou de término mudar, a API atualiza as datas dos alunos que não tiveram data alterada manualmente. Os alunos da turma recebem o curso, a carga horária e a empresa atuais da turma. A alteração gera registro na auditoria da turma.

A situação da turma não é alterada por este endpoint: o valor atual é mantido.

Corpo: mesmos campos de criar turma.

• 200: a turma alterada.
• 404: turma não encontrada.
• 422: dados inválidos.

DELETE /operational/classes/{uuid}

Apaga a turma (exclusão lógica). Não é possível apagar turma com alunos cadastrados.

• 200: "Turma deletada com sucesso!".
• 400: "Turma não pode ser deletada porque possui alunos cadastrados!".
• 404: turma não encontrada.

Ações da turma

GET /operational/classes/{uuid}/actions

Lista as ações que o usuário pode executar sobre a turma. A primeira ação é sempre o Checklist, com as condições para cancelar e concluir a turma. Quando a turma está aberta, o checklist traz cancel e conclude, cada um com allowed (indica se a ação está liberada) e a lista checklist, com o título de cada condição e se ela foi cumprida. Quando a turma não está aberta, o checklist vem vazio ([]).

As ações Cancel e Conclude aparecem para turmas abertas quando liberadas pelo checklist. A ação Reopen aparece para turmas que não estão abertas. As ações de cancelar, concluir e reabrir trazem o campo url com o caminho de execução, que não faz parte desta referência.

Resposta

• 200: lista de ações. Cada item traz title, icon e, quando houver, url ou checklist.

Exportar turmas

GET /operational/classes/export/{class_uuid?}

Gera e baixa um arquivo Excel (.xlsx) com as turmas. Aceita os mesmos filtros da listagem. Com class_uuid, exporta somente a turma informada. A exportação vai até 5.000 turmas.

• 200: download do arquivo.

Importar alunos

GET /operational/classes/import-template

Baixa o modelo de planilha (.xlsx) para a importação de alunos. A planilha tem uma linha por aluno, a partir da segunda linha; a primeira linha é o cabeçalho.

• 200: download do arquivo.

POST /operational/classes/{uuid}/import-students

Importa alunos para a turma a partir de planilha no formato Excel (.xlsx). Para cada linha, a API:

• valida o CPF do aluno e exige nome e CPF;
• usa o cadastro existente com o mesmo CPF, ou cria um cadastro de aluno;
• vincula o aluno à empresa cujo CPF ou CNPJ estiver na coluna 5, quando existir;
• cria a matrícula com a situação Matriculado, com as datas da turma e a data da prática e o valor informados.

Uma linha com erro não impede as demais. A resposta informa o total de alunos importados e as mensagens de erro, com o número da linha.

Corpo (multipart/form-data)

Campo	Obrigatório	Tipo	Descrição
file	Sim	arquivo	Planilha .xlsx no modelo da importação

• 201: {"success": true, "msg": ["Total de aluno(s) importado(s): 3"]}. Quando alguma linha tem erro, success vem false e msg traz as mensagens por linha.
• 204: arquivo não enviado. A resposta não tem conteúdo.

Exemplo

curl -X POST https://api.pedagogo.app/operational/classes/<uuid-da-turma>/import-students \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <token-de-sessao>" \
  -F "[email protected]"

Lookups da turma

GET /operational/classes/modalities

Lista as modalidades de treinamento da empresa cliente.

Parâmetros de URL: search (nome da modalidade) e per_page/page.

Resposta: lista de modalidades com uuid e nome.

GET /operational/classes/courses

Lista os cursos da empresa cliente, com o grupo a que pertencem.

Parâmetros de URL

Parâmetro	Descrição
search	Busca no nome, na sigla, no código, no uuid e no grupo do curso
group_uuid	Grupo do curso (uuid)
group_id	Grupo do curso (identificador)
practical	true para cursos com carga prática; false para cursos sem carga prática
per_page	Quantidade por página
page	Número da página, com per_page

Resposta: lista de cursos, com uuid, code, course, short_name, workload, group_uuid e group_name, entre outros campos do cadastro do curso.

Para ver um curso específico, o cadastro de cursos do módulo Comercial tem o endpoint GET /comercial/courses/{uuid}, descrito em Cursos.

GET /operational/classes/locations

Lista os locais de treinamento da empresa cliente.

Parâmetros de URL: search (nome do local ou valor da diária), customer_vendor_id (empresa dona do local, identificador numérico), per_page/page.

Resposta: lista de locais, com uuid, name, daily_rate, customer_vendor_name e a empresa dona do local.

GET /operational/classes/business

Lista as empresas (clientes) ativas da empresa cliente do usuário, para escolher a empresa da turma e dos alunos.

Parâmetros de URL

Parâmetro	Descrição
search	Busca no nome, na razão social, no documento e no uuid
name	Nome ou razão social
document	Documento (CPF ou CNPJ)
per_page	Quantidade por página
page	Número da página, com per_page
limit	Número máximo de registros
columnName	Coluna de ordenação, com orderData
orderData	Sentido da ordenação: asc ou desc

Resposta: lista de empresas, com uuid, name, company_name, document, dados de contato e endereço.

GET /operational/classes/business/{customer_vendor_uuid}/cost-centers

Lista os centros de custo de uma empresa. Use o uuid da empresa obtido em /operational/classes/business.

Parâmetros de URL: search (nome do centro de custo), per_page e page.

Resposta: lista de centros de custo, com id, cost_center, customer_vendor_id e o nome da empresa.

• 404: a empresa não é da empresa cliente do usuário.