Turmas

Turma é a realização presencial de um curso: tem data de início e de término, período, modalidade, alunos, instrutores, despesas e certificados. Cada turma é criada a partir de um curso, e a carga horária vem dele.

Esta página documenta a raiz do recurso, /comercial/classes: o cadastro da turma, as ações sobre ela (cancelar, concluir, reabrir, importar alunos e alterar a validade) e as listas de apoio usadas nos formulários. A tela principal é Turmas. Cada aba da página da turma tem a sua própria página, listada abaixo. Os documentos impressos da turma estão em Relatórios e documentos da turma.

Recursos desta seção

Recurso	Tela	Página
Turma	Turmas	Esta página
Alunos	Turmas > Alunos	Alunos
Datas de treinamento	Turmas > Datas de treinamento	Datas de treinamento
Instrutores	Turmas > Instrutores	Instrutores
Despesas	Turmas > Despesas	Despesas
Arquivos	Turmas > Arquivos do aluno e Arquivos da classe	Arquivos
Certificados	Turmas > Certificados	Certificados
Auditorias	Turmas > Auditorias	Auditorias
Pagamentos	Turmas > Alunos > Pagamentos	Pagamentos
Qualificações	Turmas > Qualificações	Qualificações
Relatórios e documentos	Turmas > Documentos da turma	Relatórios e documentos

Todas as chamadas seguem as regras de Convenções (cabeçalhos, paginação, erros e acesso por tela).

Endpoints

Método	Caminho	Descrição
`GET`	`/comercial/classes`	Lista as turmas, com filtros e paginação
`POST`	`/comercial/classes`	Cria uma turma
`GET`	`/comercial/classes/{uuid}`	Consulta uma turma
`PUT`	`/comercial/classes/{uuid}`	Altera uma turma
`DELETE`	`/comercial/classes/{uuid}`	Apaga uma turma que não tem alunos
`POST`	`/comercial/classes/get-end-date`	Calcula a data de término da turma
`GET`	`/comercial/classes/{uuid}/actions`	Lista as ações disponíveis para a turma, com o checklist
`PATCH`	`/comercial/classes/{uuid}/cancel`	Cancela a turma
`PATCH`	`/comercial/classes/{uuid}/conclude`	Conclui a turma
`PATCH`	`/comercial/classes/{uuid}/reopen`	Reabre a turma
`POST`	`/comercial/classes/{uuid}/import-students`	Importa alunos por planilha
`POST`	`/comercial/classes/change-validity`	Altera a validade dos alunos das turmas selecionadas
`GET`	`/comercial/classes/export/{class_uuid?}`	Exporta a listagem de turmas em Excel
`GET`	`/comercial/classes/import-template`	Baixa a planilha modelo de importação de alunos
`GET`	`/comercial/classes/actions`	Lista de apoio: catálogo das ações de auditoria
`GET`	`/comercial/classes/audits/actions`	Lista de apoio: catálogo das ações de auditoria (mesma consulta)
`GET`	`/comercial/classes/audits/students`	Lista de apoio: matrículas sem turma vinculada
`GET`	`/comercial/classes/check-schedule`	Lista de apoio: confere se o aluno já tem matrícula no período
`GET`	`/comercial/classes/companies`	Lista de apoio: filiais do cliente
`GET`	`/comercial/classes/courses`	Lista de apoio: cursos
`GET`	`/comercial/classes/courses/{uuid}`	Lista de apoio: detalhe de um curso
`GET`	`/comercial/classes/modalities`	Lista de apoio: modalidades
`GET`	`/comercial/classes/periods`	Lista de apoio: períodos das aulas
`GET`	`/comercial/classes/statuses`	Lista de apoio: status da turma
`GET`	`/comercial/classes/business`	Lista de apoio: empresas do cadastro de clientes
`GET`	`/comercial/classes/business/{customer_vendor_uuid}/cost-centers`	Lista de apoio: centros de custo da empresa
`POST`	`/comercial/classes/business/{customer_vendor_uuid}/cost-centers`	Cadastra um centro de custo da empresa
`GET`	`/comercial/classes/expenses/customers-vendors`	Lista de apoio: fornecedores das despesas
`GET`	`/comercial/classes/expenses/types`	Lista de apoio: tipos de despesa
`GET`	`/comercial/classes/files/students`	Lista de apoio: matrículas sem turma vinculada
`GET`	`/comercial/classes/food-vouchers`	Lista de apoio: vouchers de alimentação
`GET`	`/comercial/classes/accommodation-vouchers`	Lista de apoio: vouchers de hospedagem
`GET`	`/comercial/classes/instructors`	Lista de apoio: instrutores
`GET`	`/comercial/classes/instructors/responsables-types`	Lista de apoio: tipos de responsável
`GET`	`/comercial/classes/instructors/{employee_id}/specializations`	Lista de apoio: especializações do instrutor
`GET`	`/comercial/classes/students`	Lista de apoio: alunos do cadastro do cliente
`GET`	`/comercial/classes/students/food-vouchers`	Lista de apoio: vouchers de alimentação
`GET`	`/comercial/classes/students/accommodation-vouchers`	Lista de apoio: vouchers de hospedagem
`GET`	`/comercial/classes/students/agent`	Lista de apoio: usuários do cliente
`GET`	`/comercial/classes/students/responsible`	Lista de apoio: usuários do cliente
`POST`	`/comercial/classes/students/{uuid}/photo`	Envia a foto de um aluno
`DELETE`	`/comercial/classes/students/{uuid}/photo`	Remove a foto de um aluno

Criar, listar e consultar

GET /comercial/classes

Lista as turmas do cliente. Sem ordenação informada, a lista vem da data de início mais recente para a mais antiga e, dentro de cada data de início, da data de término mais antiga para a mais recente. Com column e order, a ordenação usa esses campos. Com per_page, a resposta é paginada.

Parâmetros de URL

Parâmetro	Descrição
`search`	Texto livre: código da turma, curso (nome, código e sigla), comentários e dados de alunos e empresas da turma
`code`	Código da turma
`company_id` / `company_uuid`	Filial (empresa cliente) da turma
`customer_vendor_business_id`	Empresa do cadastro de clientes vinculada à turma
`course_id` / `course_uuid`	Curso da turma
`period_id`	Período das aulas
`status_id`	Status da turma
`modality_id` / `modality_uuid`	Modalidade da turma
`class_uuid`	Uma turma específica
`class_uuids`	Lista de turmas, pelos uuids
`not_class_uuid`	Exclui uma turma da lista
`start_date` e `end_date`	Período. Com os dois, a turma deve começar e terminar dentro do intervalo. Com apenas um, filtra essa data de início ou de término
`limit`	Quantidade máxima de registros
`column` e `order`	Campo e sentido da ordenação
`per_page` e `page`	Paginação (ver Listagens em Convenções)

Resposta

Status 200. Lista de turmas, ou resposta paginada quando per_page é informado. Os campos principais são uuid, code, course_uuid, course_name, course_code, period, modality_name, company_name, start_date, end_date, status_name, student_count, location_name, user_create_name e user_update_name.

POST /comercial/classes

Cria a turma. O sistema gera o código sequencial da turma para o cliente e copia a carga horária do curso escolhido. A criação grava um registro na auditoria da turma. A data de término não pode ser anterior à data de início.

Corpo

Campo	Obrigatório	Tipo	Descrição
`course_uuid`	Sim	texto (uuid)	Curso da turma
`modality_uuid`	Sim	texto (uuid)	Modalidade do treinamento
`period_id`	Sim	número inteiro	Período das aulas
`daily_workload`	Sim	número inteiro	Horas de treinamento por dia
`start_date`	Sim	data	Primeiro dia da turma
`end_date`	Sim	data	Data de término. Não pode ser anterior à data de início
`weekend_day`	Não	número inteiro	Dia do fim de semana, usado quando o período é de fim de semana
`vacancies`	Não	número inteiro	Número de vagas
`company_uuid`	Não	texto (uuid)	Filial (empresa cliente) à qual a turma pertence
`location_uuid`	Não	texto (uuid)	Local de realização
`status_id`	Não	número inteiro	Status da turma
`comments`	Não	texto	Observações internas sobre a turma
`justification`	Não	texto	Texto registrado na auditoria da criação

Resposta

Status 201, com a turma criada (inclui uuid e code).

curl -X POST "https://api.pedagogo.app/comercial/classes" \
  -H "Authorization: Bearer <token-de-sessao>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "course_uuid": "<uuid-do-curso>",
    "modality_uuid": "<uuid-da-modalidade>",
    "period_id": 1,
    "daily_workload": 8,
    "start_date": "2026-03-02",
    "end_date": "2026-03-13",
    "vacancies": 20,
    "comments": "Turma exemplo"
  }'

GET `/comercial/classes/{uuid}`

Consulta uma turma, com o curso e os credenciamentos dele, o status, a empresa, a modalidade e a quantidade de alunos. Status 404 quando a turma não existe ou pertence a outro cliente.

PUT `/comercial/classes/{uuid}`

Altera a turma. O corpo segue as mesmas regras do cadastro. O status não muda por esta rota: ele é mantido, e a mudança de status é feita pelas ações de cancelar, concluir e reabrir, descritas nesta página.

Corpo

Campo	Obrigatório	Tipo	Descrição
`course_uuid`	Sim	texto (uuid)	Curso da turma. Se for trocado, a carga horária passa a ser a do novo curso
`modality_uuid`	Sim	texto (uuid)	Modalidade do treinamento
`period_id`	Sim	número inteiro	Período das aulas
`daily_workload`	Sim	número inteiro	Horas de treinamento por dia
`start_date`	Sim	data	Primeiro dia da turma
`end_date`	Sim	data	Data de término. Não pode ser anterior à data de início
`weekend_day`	Não	número inteiro	Dia do fim de semana
`vacancies`	Não	número inteiro	Número de vagas
`company_uuid`	Não	texto (uuid)	Filial (empresa cliente)
`location_uuid`	Não	texto (uuid)	Local de realização
`status_id`	Não	número inteiro	Não altera o status (ver acima)

Resposta

Status 200, com a turma alterada.

Quando as datas da turma mudam, os alunos que não têm a opção de datas próprias (Alterar data desmarcada) recebem as novas datas. A alteração grava um registro na auditoria da turma, com as datas antigas e novas. Os alunos da turma também recebem a carga horária, o curso e a empresa da turma, além do responsável e do representante conforme o cadastro.

DELETE `/comercial/classes/{uuid}`

Apaga a turma (exclusão lógica). Se a turma tem alunos cadastrados, a resposta é 400 com a mensagem de que a turma não pode ser apagada.

Resposta

Status 200, com a mensagem de confirmação, ou 400 quando há alunos na turma.

POST /comercial/classes/get-end-date

Calcula a data de término da turma a partir do curso, do período, da data de início, da carga horária diária e do dia de fim de semana. É a conta usada no campo Data de término, que não pode ser digitado. Quando class_uuid é informado, a carga horária usada é a da turma, e não a do curso.

Corpo

Campo	Obrigatório	Tipo	Descrição
`course_uuid`	Sim	texto (uuid)	Curso da turma
`period_id`	Sim	número inteiro	Período das aulas
`start_date`	Sim	data	Data de início
`daily_workload`	Sim	número inteiro	Horas de treinamento por dia
`weekend_day`	Não	número inteiro	Dia do fim de semana
`class_uuid`	Não	texto (uuid)	Turma, para usar a carga horária dela

Resposta

Status 200, com a data e hora de término no formato AAAA-MM-DD HH:MM:SS.

GET `/comercial/classes/{uuid}/actions`

Lista as ações disponíveis para a turma. A primeira entrada é o Checklist, com o resultado das condições de cancelamento e de conclusão. Cada condição traz o título e se está atendida (allowed). Para turma que não está Aberta, o checklist vem vazio. As demais entradas são ações, cada uma com title, url relativa e icon:

turma Aberta: entradas de cancelar e de concluir, quando a condição correspondente está atendida;
turma que não está Aberta: entrada de reabrir.

[
  {
    "title": "Checklist",
    "icon": "...",
    "checklist": {
      "cancel": { "allowed": true, "checklist": [ { "title": "...", "allowed": true } ] },
      "conclude": { "allowed": false, "checklist": [ { "title": "...", "allowed": false } ] }
    }
  },
  { "title": "...", "url": "comercial/classes/<uuid-da-turma>/cancel", "icon": "..." }
]

PATCH `/comercial/classes/{uuid}/cancel`

Cancela a turma, que passa para Cancelada, e todos os alunos passam para Cancelado. Só vale para turma Aberta em que nenhum aluno tem pagamento registrado. A ação grava um registro na auditoria.

Resposta

Status 200, com a mensagem Turma cancelada com sucesso!. Status 400 quando a turma não pode ser cancelada.

PATCH `/comercial/classes/{uuid}/conclude`

Conclui a turma. Só vale para turma Aberta com o checklist de conclusão atendido, que exige:

a turma ter pelo menos um aluno;
nenhum aluno estar apenas como Matriculado ou Confirmado;
todos os alunos terem CPF ou passaporte cadastrado. Alunos Cancelados, Ausentes ou Não concluídos não entram nessa conferência;
para alunos particulares (sem empresa), o total pago ser igual ao total do valor do curso desses alunos.

Ao concluir, o sistema faz as etapas abaixo de uma vez. Se uma delas falhar, nenhuma é aplicada:

marca a turma como Concluída e grava um registro na auditoria;
gera os certificados dos alunos Aprovados que ainda não têm certificado ativo;
atualiza o responsável e o representante de cada aluno, conforme o cadastro da empresa ou do aluno.

Resposta

Status 200, com a mensagem Turma concluída com sucesso!. Status 400 quando o checklist não está atendido.

PATCH `/comercial/classes/{uuid}/reopen`

Reabre a turma, que volta para Aberta. Não é possível reabrir uma turma que já está Aberta. A reabertura não restaura o status dos alunos: os alunos Cancelados continuam nesse status e precisam ser ajustados um a um.

Corpo

Campo	Obrigatório	Tipo	Descrição
`justification`	Não	texto	Justificativa da reabertura, registrada na auditoria

Resposta

Status 200, com a mensagem Turma reaberta com sucesso!. Status 400 com a mensagem de que o status da turma não permite reabertura, quando a turma já está Aberta. Status 403 quando a ação não está liberada para o usuário.

POST `/comercial/classes/{uuid}/import-students`

Importa alunos por planilha Excel (xlsx) no campo file. O envio é feito como multipart/form-data. Cada linha válida vira uma matrícula na turma, com status Matriculado e com as datas da turma. As linhas sem nome, sem CPF ou com CPF inválido são recusadas. Se o CPF já existe no cadastro de alunos do cliente, o cadastro existente é usado; se não existe, o aluno é criado.

As colunas da planilha, na ordem, são:

Nome (obrigatório)
CPF (obrigatório, válido)
Passaporte
Data de nascimento
CPF ou CNPJ da empresa
E-mail
Celular
Data da prática
Valor

A planilha modelo está em GET /comercial/classes/import-template.

Corpo

Campo	Obrigatório	Tipo	Descrição
`file`	Não	arquivo xlsx	Planilha com os alunos. Sem o arquivo, nenhum aluno é importado

Resposta

Status 201, com success e msg. msg traz uma mensagem para cada linha recusada, com o número da linha, e o total de alunos importados.

POST /comercial/classes/change-validity

Altera a validade, em meses, de todos os alunos das turmas selecionadas. As turmas são escolhidas pelos mesmos filtros da listagem de turmas, como class_uuids. A alteração grava um registro na auditoria de cada turma.

Corpo

Campo	Obrigatório	Tipo	Descrição
`validity`	Não	número inteiro	Validade, em meses
`class_uuids`	Não	lista de textos (uuid)	Turmas selecionadas

Resposta

Status 200, sem conteúdo útil (null).

GET `/comercial/classes/export/{class_uuid?}`

Gera um arquivo Excel (xlsx) com a listagem de turmas, com os mesmos filtros de GET /comercial/classes. Quando class_uuid é informado no caminho, a exportação traz só essa turma. A exportação traz até 5.000 turmas. O arquivo é gerado na própria chamada e devolvido como download.

Resposta

Status 200, com o arquivo xlsx.

GET /comercial/classes/import-template

Baixa a planilha modelo de importação de alunos (xlsx), usada em POST /comercial/classes/{uuid}/import-students.

Resposta

Status 200, com o arquivo xlsx.

Listas de apoio

As listas abaixo alimentam os formulários da turma e as abas. Elas seguem as regras de listagem de Convenções: com per_page a resposta é paginada, sem ele vem a lista completa. Os filtros aceitos estão indicados em cada item.

GET /comercial/classes/actions e GET /comercial/classes/audits/actions: catálogo das ações registradas nas auditorias da turma. Cada item traz id, action (nome da ação), status_id e status. As duas rotas devolvem a mesma consulta.
GET /comercial/classes/audits/students e GET /comercial/classes/files/students: matrículas sem turma vinculada, com os filtros de matrícula. Usam a mesma consulta.
GET /comercial/classes/check-schedule: confere se o aluno tem matrícula que coincide com o período informado. Parâmetros: customer_vendor_student_id (obrigatório), start_date (obrigatório), end_date e uuid (matrícula a ignorar). Devolve a matrícula mais recente que coincide, com curso e turma, ou null.
GET /comercial/classes/companies: filiais (empresas cliente) do cliente. É a lista do campo Filial.
GET /comercial/classes/courses: cursos do cliente. Aceita search, group_uuid e group_id.
GET /comercial/classes/courses/{uuid}: um curso. É a fonte da carga horária e da validade preenchidas ao escolher o curso.
GET /comercial/classes/modalities: modalidades do cliente. Aceita search.
GET /comercial/classes/periods: períodos das aulas, com id e period.
GET /comercial/classes/statuses: status da turma, com id e status.
GET /comercial/classes/business: empresas do cadastro de clientes, ativas, usadas como empresa do aluno.
GET /comercial/classes/business/{customer_vendor_uuid}/cost-centers: centros de custo da empresa informada.
GET /comercial/classes/expenses/customers-vendors: fornecedores, usados no campo Fornecedor das despesas.
GET /comercial/classes/expenses/types: tipos de despesa cadastrados pelo cliente.
GET /comercial/classes/instructors: instrutores cadastrados.
GET /comercial/classes/instructors/responsables-types: tipos de responsável, que definem o papel do instrutor na turma.
GET /comercial/classes/instructors/{employee_id}/specializations: especializações do instrutor informado.
GET /comercial/classes/students: alunos do cadastro do cliente, com paginação.
GET /comercial/classes/food-vouchers e GET /comercial/classes/students/food-vouchers: vouchers de alimentação cadastrados. Devolvem a mesma consulta.
GET /comercial/classes/accommodation-vouchers e GET /comercial/classes/students/accommodation-vouchers: vouchers de hospedagem cadastrados. Devolvem a mesma consulta.
GET /comercial/classes/students/agent e GET /comercial/classes/students/responsible: usuários do cliente, com search e paginação. Devolvem a mesma consulta.

POST `/comercial/classes/business/{customer_vendor_uuid}/cost-centers`

Cadastra um centro de custo na empresa informada no caminho.

Corpo

Campo	Obrigatório	Tipo	Descrição
`cost_center`	Sim	texto	Nome ou código do centro de custo

Resposta

Status 201, com o centro de custo criado.

Foto do aluno

POST `/comercial/classes/students/{uuid}/photo`

Envia a foto do aluno. O {uuid} é o do cadastro de aluno. O envio é feito como multipart/form-data, no campo file. Se o aluno já tinha foto, a anterior é substituída.

Corpo

Campo	Obrigatório	Tipo	Descrição
`file`	Não	imagem	Foto do aluno. Sem o arquivo, a foto não é alterada

Resposta

Status 200, com o cadastro do aluno.

DELETE `/comercial/classes/students/{uuid}/photo`

Remove a foto do aluno.

Resposta

Status 200, com a mensagem Foto removida com sucesso.. Status 404 quando o aluno não tem foto.

Recursos desta seção​

Endpoints​

Criar, listar e consultar​

GET /comercial/classes​

POST /comercial/classes​

GET /comercial/classes/{uuid}​

PUT /comercial/classes/{uuid}​

DELETE /comercial/classes/{uuid}​

POST /comercial/classes/get-end-date​

GET /comercial/classes/{uuid}/actions​

PATCH /comercial/classes/{uuid}/cancel​

PATCH /comercial/classes/{uuid}/conclude​

PATCH /comercial/classes/{uuid}/reopen​

POST /comercial/classes/{uuid}/import-students​

POST /comercial/classes/change-validity​

GET /comercial/classes/export/{class_uuid?}​

GET /comercial/classes/import-template​

Listas de apoio​

POST /comercial/classes/business/{customer_vendor_uuid}/cost-centers​

Foto do aluno​

POST /comercial/classes/students/{uuid}/photo​

DELETE /comercial/classes/students/{uuid}/photo​

Recursos desta seção

Endpoints

Criar, listar e consultar

GET /comercial/classes

POST /comercial/classes

GET `/comercial/classes/{uuid}`

PUT `/comercial/classes/{uuid}`

DELETE `/comercial/classes/{uuid}`

POST /comercial/classes/get-end-date

GET `/comercial/classes/{uuid}/actions`

PATCH `/comercial/classes/{uuid}/cancel`

PATCH `/comercial/classes/{uuid}/conclude`

PATCH `/comercial/classes/{uuid}/reopen`

POST `/comercial/classes/{uuid}/import-students`

POST /comercial/classes/change-validity

GET `/comercial/classes/export/{class_uuid?}`

GET /comercial/classes/import-template

Listas de apoio

POST `/comercial/classes/business/{customer_vendor_uuid}/cost-centers`

Foto do aluno

POST `/comercial/classes/students/{uuid}/photo`

DELETE `/comercial/classes/students/{uuid}/photo`