Alunos da turma

Os alunos matriculados em uma turma. Na tela, ficam na aba Turmas > Alunos da página da turma. Cada item é uma matrícula na turma, identificada pelo uuid do aluno na turma, e está ligada ao cadastro de aluno. Os pagamentos do aluno estão na página Pagamentos do aluno na turma.

Nas rotas desta página, {class_uuid} é o uuid da turma (ver Turmas) e {uuid} é o uuid do aluno na turma, salvo onde a descrição disser outra coisa.

Endpoints

Método	Caminho	Descrição
GET	/comercial/classes/{class_uuid}/students	Lista os alunos da turma
POST	/comercial/classes/{class_uuid}/students	Matricula um aluno na turma
GET	/comercial/classes/{class_uuid}/students-files	Lista os arquivos do cadastro dos alunos da turma
POST	/comercial/classes/{class_uuid}/students/batch-change	Altera valor, empresa ou vale-refeição de vários alunos
POST	/comercial/classes/{class_uuid}/students/change-status	Muda o status de vários alunos
GET	/comercial/classes/{class_uuid}/students/files	Lista os arquivos da turma vinculados aos alunos
GET	/comercial/classes/{class_uuid}/students/reports/training-confirmation-letter	Gera a declaração de confirmação de treinamento
GET	/comercial/classes/{class_uuid}/students/reports/training-confirmation-letter-business	Gera a declaração de confirmação para a empresa
GET	/comercial/classes/{class_uuid}/students/{student_uuid}/attendance-record-report	Gera a lista de presença individual do aluno
GET	/comercial/classes/{class_uuid}/students/{student_uuid}/contract	Gera o contrato do aluno
GET	/comercial/classes/{class_uuid}/students/{student_uuid}/previous-training-business	Consulta a empresa da turma mais recente do aluno (lista de apoio)
GET	/comercial/classes/{class_uuid}/students/{uuid}	Consulta um aluno da turma
PUT	/comercial/classes/{class_uuid}/students/{uuid}	Altera os dados de um aluno da turma
DELETE	/comercial/classes/{class_uuid}/students/{uuid}	Remove o aluno da turma
PATCH	/comercial/classes/{class_uuid}/students/{uuid}/send-registration-link-by-email	Envia por e-mail o link de cadastro da assinatura eletrônica
PATCH	/comercial/classes/{class_uuid}/students/{uuid}/send-registration-link-by-whatsapp	Envia por WhatsApp o link de cadastro da assinatura eletrônica
GET	/comercial/classes/{class_uuid}/students/{uuid}/show-signature	Baixa a assinatura eletrônica cadastrada pelo aluno
GET	/comercial/classes/{class_uuid}/students/{uuid}/transfer-class	Lista as turmas para onde o aluno pode ser transferido (lista de apoio)
POST	/comercial/classes/{class_uuid}/students/{uuid}/transfer-class	Transfere o aluno para outra turma

Status do aluno

O campo status_id usa estes valores, nas rotas de status e nos filtros da listagem.

status_id	Status
1	Matriculado
2	Aprovado
3	Reprovado
4	Confirmado
5	Cancelado
6	Ausente
7	Não concluído

Consultar e alterar

GET /comercial/classes/{class_uuid}/students

Lista os alunos da turma informada na URL.

Parâmetros de URL

Parâmetro	Descrição
search	Texto livre para buscar nas colunas principais, como o nome do aluno
status_id	Mostra só os alunos com o status informado. Aceita uma lista de status
not_status_id	Deixa de fora os alunos com o status informado. Aceita uma lista de status
column e order	Ordena pela coluna informada, em asc ou desc
per_page e page	Paginação. Sem per_page, a resposta é a lista completa

Resposta: 200. Cada item traz o uuid do aluno na turma, as datas, o valor, o status e os dados do cadastro (nome e documento).

POST /comercial/classes/{class_uuid}/students

Matricula um aluno na turma.

Corpo

Campo	Obrigatório	Tipo	Descrição
customer_vendor_student_id	Sim	Número	Id do cadastro do aluno
company_id	Não	Número	Id da empresa vinculada ao aluno na turma
customer_vendor_business_id	Não	Número	Id da empresa que paga pelo aluno
cost_center_id	Não	Número	Id do centro de custo da empresa
contract_course_id	Não	Número	Id do contrato do curso vinculado ao aluno
change_date	Não	Booleano	Quando verdadeiro, o aluno usa as datas informadas em start_date e end_date. Sem ele, o aluno segue as datas da turma
start_date	Não	Data	Data de início do aluno, usada quando change_date é verdadeiro
end_date	Não	Data	Data de término do aluno, usada quando change_date é verdadeiro

A matrícula entra com o status Matriculado. Se o cadastro já estava nesta turma, inclusive apagado, o registro existente é reativado e atualizado, em vez de criar outro. Quando o aluno tem empresa pagadora, o contrato do curso, se houver, define o contrato e o valor.

Resposta: 200 com o aluno criado, incluindo o uuid do aluno na turma.

curl -X POST "https://api.pedagogo.app/comercial/classes/<uuid-da-turma>/students" \
  -H "Authorization: Bearer <token-de-sessao>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"customer_vendor_student_id": 123, "company_id": 45}'

GET /comercial/classes/{class_uuid}/students-files

Lista os arquivos do cadastro dos alunos da turma, como o tipo do arquivo, a descrição e a validade.

Parâmetros de URL

Parâmetro	Descrição
search	Texto livre para buscar pelo tipo do arquivo
columnName e orderData	Ordena pela coluna informada, em asc ou desc
per_page e page	Paginação

Resposta: 200, lista de arquivos com o arquivo armazenado (upload).

GET /comercial/classes/{class_uuid}/students/files

Lista os arquivos da turma vinculados aos alunos, como certificados armazenados e documentos de entrega. É a aba Turmas > Arquivos do aluno.

Parâmetros de URL

Parâmetro	Descrição
search	Texto livre para buscar pelo nome do aluno
column e order	Ordena pela coluna informada, em asc ou desc
per_page e page	Paginação

Resposta: 200, lista de arquivos com o arquivo armazenado (upload) e a descrição.

POST /comercial/classes/{class_uuid}/students/batch-change

Altera valor, empresa e vale-refeição de vários alunos de uma vez. Na tela, é a ação Alterar dados em lote.

Corpo

Campo	Obrigatório	Tipo	Descrição
students_uuid	Sim	Lista	uuid dos alunos na turma
amount	Não	Número	Novo valor do treinamento
customer_vendor_business_id	Não	Número	Id da empresa que passa a pagar pelo aluno
vourcher_food_id	Não	Número	Id do vale-refeição a aplicar

Regras e efeitos:

• Em turma cancelada, a alteração é recusada.
• Com amount, o aluno de empresa que tem contrato do curso é ignorado. O aluno sem empresa com pagamentos cujo total é maior que o novo valor recebe erro.
• Com customer_vendor_business_id, o aluno sem empresa que tem pagamentos registrados ou faturamento recebe erro. Se o cliente tem contrato para o curso do aluno, o valor e o contrato vêm dele.
• As alterações válidas são gravadas mesmo quando outros alunos da lista recebem erro.

Resposta: 200 com {"message": "Dados alterados com sucesso."}. Quando algum aluno não pôde ser alterado, 400 com a lista errors, com uma mensagem por aluno.

POST /comercial/classes/{class_uuid}/students/change-status

Muda o status de vários alunos da turma.

Corpo

Campo	Obrigatório	Tipo	Descrição
students_uuid	Sim	Lista	uuid dos alunos na turma
status_id	Sim	Número	Novo status, conforme a tabela Status do aluno

Regras, aplicadas a cada aluno:

• A turma precisa estar Aberta. Em outro status, a resposta é 400 com {"message": "Não é possível alterar o status de um aluno de uma turma não aberta."}.
• Aprovado, Reprovado e Não concluído exigem a data de término do aluno.
• Aprovado exige CPF ou passaporte cadastrado para o aluno.
• Aprovado ou Reprovado de aluno sem empresa exige que o total pago e enviado ao financeiro seja igual ao valor do aluno.
• Cancelado de aluno sem empresa só é aceito sem pagamentos registrados.
• Alunos de empresa não passam pela checagem de pagamento.

Efeitos: o responsável e o agente do aluno são atualizados, os certificados ativos do aluno são marcados como cancelados e a solicitação de treinamento vinculada, quando existir, acompanha o novo status.

Resposta: 200 com {"message": "Status alterado com sucesso."}. Quando algum aluno não pôde ser alterado, 400 com a lista errors, com uma mensagem por aluno. Os demais alunos já foram alterados.

{
  "errors": [
    "Data de término do aluno Aluno exemplo não informada."
  ]
}

GET /comercial/classes/{class_uuid}/students/reports/training-confirmation-letter

Gera a declaração de confirmação de treinamento dos alunos informados, em PDF. Na tela, é a opção Visualizar carta de confirmação.

Parâmetros de URL

Parâmetro	Descrição
uuids	Lista de uuid dos alunos na turma a incluir na declaração

Resposta: 200 com o arquivo PDF para download. Sem aluno selecionado, 400 com {"error": "Nenhum aluno selecionado"}. O modelo do documento pode variar conforme o cadastro do cliente.

GET /comercial/classes/{class_uuid}/students/reports/training-confirmation-letter-business

Gera a declaração de confirmação de treinamento para a empresa, em PDF. Recebe os mesmos parâmetros e tem as mesmas respostas da declaração anterior.

GET /comercial/classes/{class_uuid}/students/{student_uuid}/attendance-record-report

Gera a lista de presença individual do aluno, em PDF. Na tela, é a opção Lista de presença individual.

Resposta: 200 com o arquivo PDF para download.

GET /comercial/classes/{class_uuid}/students/{student_uuid}/contract

Gera o contrato do aluno, em PDF, conforme o modelo de contrato cadastrado para o cliente. Na tela, a opção Visualizar contrato aparece somente para alunos que não estão vinculados a uma empresa.

Resposta: 200 com o arquivo PDF para download.

GET /comercial/classes/{class_uuid}/students/{uuid}

Consulta um aluno da turma, com os dados da turma, do curso e os complementos do cadastro.

Resposta: 200 com o aluno. Se o aluno não existir, a resposta não traz dados.

PUT /comercial/classes/{class_uuid}/students/{uuid}

Altera os dados de um aluno da turma. Na tela, é a ação Editar da linha do aluno.

Corpo

Campo	Obrigatório	Tipo	Descrição
customer_vendor_student_id	Não	Número	Id do cadastro do aluno
company_id	Não	Número	Id da empresa que paga pelo aluno
cost_center_id	Não	Número	Id do centro de custo da empresa
contract_course_id	Não	Número	Id do contrato do curso vinculado ao aluno

Outros dados do aluno, como valor e datas, também podem ser enviados.

Regras e efeitos:

• O valor do aluno não fica abaixo do total já pago.
• Para alunos Matriculado ou Confirmado, a validade e a carga horária são recalculadas a partir do curso.
• Para os demais status, o cadastro do aluno e a empresa não são trocados, e a alteração entra na auditoria da turma, com a ação de dados alterados.
• Se o aluno tem faturamento registrado, a empresa não é trocada.

Resposta: 200 com o aluno alterado.

PATCH /comercial/classes/{class_uuid}/students/{uuid}/send-registration-link-by-email

Envia por e-mail o link para o aluno fazer o cadastro da assinatura eletrônica, usado na emissão do certificado. O e-mail vai para o cadastro do aluno. O {uuid} desta rota é o identificador do cadastro do aluno.

Resposta: 200, sem corpo.

PATCH /comercial/classes/{class_uuid}/students/{uuid}/send-registration-link-by-whatsapp

Envia por WhatsApp o link de cadastro da assinatura eletrônica. O envio só acontece se o cadastro do aluno tem celular. O {uuid} desta rota é o identificador do cadastro do aluno.

Resposta: 200, sem corpo.

GET /comercial/classes/{class_uuid}/students/{uuid}/show-signature

Baixa a assinatura eletrônica cadastrada pelo aluno. Na tela, é a opção Visualizar assinatura, que aparece quando o aluno já tem assinatura. O {uuid} desta rota é o identificador do cadastro do aluno.

Resposta: 200 com o arquivo da assinatura para download. Sem assinatura cadastrada, 200 com {"success": true, "message": "Assinatura não encontrada."}. Se o arquivo não puder ser baixado, 500 com success igual a false e a mensagem do erro.

DELETE /comercial/classes/{class_uuid}/students/{uuid}

Remove o aluno da turma. Junto com o aluno, são apagadas as despesas e os certificados vinculados a ele, e a exclusão da matrícula é enviada aos sistemas integrados.

Resposta: 200, sem corpo.

Transferência de turma

GET /comercial/classes/{class_uuid}/students/{uuid}/transfer-class

Lista as turmas para onde o aluno pode ser transferido. Mostra as turmas Abertas. Para aluno Aprovado em turma Concluída, mostra as turmas Concluídas. A turma atual não aparece na lista.

Parâmetros de URL

Parâmetro	Descrição
search	Texto livre para buscar nas turmas
column e order	Ordena pela coluna informada, em asc ou desc
per_page e page	Paginação

Resposta: 200, lista de turmas no mesmo formato da listagem de turmas.

POST /comercial/classes/{class_uuid}/students/{uuid}/transfer-class

Transfere o aluno para outra turma. Na tela, é a ação Transferir aluno.

Corpo

Campo	Obrigatório	Tipo	Descrição
new_class_uuid	Sim	Texto	uuid da turma de destino

Regras:

• Aluno Aprovado só é transferido para turma Concluída.
• Aluno Matriculado ou Confirmado não é transferido para turma Concluída.

Efeitos: o aluno assume a turma, o curso, a carga horária, a validade, a empresa e as datas da nova turma. As despesas do aluno na turma de origem passam para a turma de destino. A auditoria das duas turmas registra a saída e a entrada.

Resposta: 200 com a mensagem "Aluno transferido com sucesso!". Quando alguma regra não é atendida, 400 com a mensagem da regra.

Listas auxiliares

• Turmas de transferência (GET .../transfer-class): turmas que podem receber o aluno, conforme o status do aluno e da turma.
• Empresa anterior (GET .../{student_uuid}/previous-training-business): devolve a empresa vinculada à turma mais recente do aluno, com business_id, business_name e business_document. Sem empresa anterior, a resposta é null. O {student_uuid} desta rota é o identificador do cadastro do aluno.

Para as demais regras de gestão dos alunos, veja a página Turmas.