Alunos da turma
Aluno da turma é a matrícula de um aluno cadastrado em uma turma, com a empresa, o centro de custo, a situação e as datas do treinamento. Esta página cobre os endpoints de matrícula, alteração de situação e consulta da aba de alunos da turma. Os cadastros de alunos e de empresas ficam em outros módulos.
No manual de usuário, esta área é a aba Alunos da turma, dentro do detalhe da turma (módulo Operacional).
Os endpoints desta página usam o class_uuid da turma no caminho. As regras gerais estão em Convenções e a sessão em Autenticação. Os dados da turma estão em Turmas.
Endpoints
| Método | Caminho | Descrição |
|---|---|---|
| GET | /operational/classes/{class_uuid}/students | Lista os alunos matriculados na turma |
| POST | /operational/classes/{class_uuid}/students | Matricula um aluno na turma |
| GET | /operational/classes/{class_uuid}/students/{uuid} | Consulta a matrícula de um aluno na turma |
| PUT | /operational/classes/{class_uuid}/students/{uuid} | Altera a matrícula de um aluno na turma |
| DELETE | /operational/classes/{class_uuid}/students/{uuid} | Remove a matrícula de um aluno da turma |
| POST | /operational/classes/{class_uuid}/students/change-status | Altera a situação de um ou mais alunos |
| GET | /operational/classes/students | Lista os cadastros de alunos, para escolher o aluno da matrícula |
| GET | /operational/classes/students/responsible | Lista os usuários que podem ser responsáveis pelo aluno |
| GET | /operational/classes/students/agent | Lista os usuários que podem ser agentes do aluno |
| GET | /operational/classes/students/statuses | Lista as situações do aluno na turma |
Listar alunos da turma
GET /operational/classes/{class_uuid}/students
Lista as matrículas da turma informada, com os dados do aluno (nome, documento, passaporte, contatos), da empresa, do centro de custo, da situação, do responsável, do agente, as datas do treinamento e os totais de pagamentos.
Parâmetros de URL
| Parâmetro | Descrição |
|---|---|
| search | Busca no nome, no documento, no celular, no e-mail e no curso do aluno, e no nome ou documento da empresa |
| student | Nome, e-mail, celular ou documento do aluno |
| company | Nome, e-mail, telefone ou documento da empresa do aluno |
| status_id | Situação do aluno (identificador da situação, obtido em /operational/classes/students/statuses) |
| customer_vendor_student_uuid | Cadastro do aluno (uuid do cadastro de alunos) |
| customer_vendor_business_id | Empresa do aluno (identificador numérico) |
| practice_start_date | Com practice_end_date, alunos com data da prática no intervalo. Sem ele, data da prática exata |
| practice_end_date | Com practice_start_date, alunos com data da prática no intervalo |
| 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 por nome do aluno.
Resposta
- 200: lista de matrículas ou, com
per_page, objeto paginado (veja Convenções).
Campos principais: uuid (da matrícula na turma, usado nas demais rotas desta página), customer_vendor_student_uuid (do cadastro do aluno), student_name, student_document, student_passport, status_id, status_name, company_name, business_name, cost_center, responsible_name, agent_name, amount, start_date, end_date, practice_date, totalPayments, totalCompletedPayments e class_code.
Exemplo
curl "https://api.pedagogo.app/operational/classes/<uuid-da-turma>/students?search=Aluno%20exemplo&per_page=15" \
-H "Accept: application/json" \
-H "Authorization: Bearer <token-de-sessao>"
Matricular aluno
POST /operational/classes/{class_uuid}/students
Matricula um cadastro de aluno na turma. A matrícula entra com a situação Matriculado e com as datas de início e término da turma. A API preenche o curso, a carga horária e o responsável e o agente do aluno.
Se o aluno já estiver na turma, a API não cria outra matrícula: devolve a matrícula existente, atualizada com os dados enviados.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| customer_vendor_student_id | Sim | inteiro | Cadastro do aluno (identificador do cadastro de alunos) |
| company_id | Não | inteiro | Empresa do aluno (identificador numérico do cadastro de empresas) |
| cost_center_id | Não | inteiro | Centro de custo da empresa escolhida |
| contract_course_id | Não | inteiro | Contrato do curso ao qual a matrícula está ligada |
Resposta
- 200: a matrícula criada ou existente.
- 404: turma não encontrada.
- 422: dados inválidos.
Exemplo
curl -X POST https://api.pedagogo.app/operational/classes/<uuid-da-turma>/students \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token-de-sessao>" \
-d '{
"customer_vendor_student_id": 123,
"cost_center_id": 45
}'
Consultar, alterar e remover a matrícula
GET /operational/classes/{class_uuid}/students/{uuid}
Devolve a matrícula informada, com os dados do aluno, da empresa, do curso e os totais de pagamentos.
- 200: a matrícula.
- 404: matrícula não encontrada.
PUT /operational/classes/{class_uuid}/students/{uuid}
Altera a matrícula. Os campos enviados são gravados na matrícula. A API também atualiza o responsável e o agente conforme o cadastro do aluno e da empresa.
Quando a situação da matrícula não é Matriculado nem Confirmado, o vínculo com o cadastro do aluno e com a empresa não é alterado, e a alteração fica registrada na auditoria da turma.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| customer_vendor_student_id | Não | inteiro | Cadastro do aluno |
| company_id | Não | inteiro | Empresa do aluno (identificador numérico do cadastro de empresas) |
| cost_center_id | Não | inteiro | Centro de custo da empresa escolhida |
| contract_course_id | Não | inteiro | Contrato do curso ao qual a matrícula está ligada |
- 200: a matrícula alterada.
- 404: matrícula não encontrada.
- 422: dados inválidos.
DELETE /operational/classes/{class_uuid}/students/{uuid}
Remove a matrícula da turma (exclusão lógica). Também são removidas as despesas e os certificados ligados a essa matrícula, e a remoção é enviada às integrações de ensino do cliente, quando houver.
- 200: sem conteúdo.
- 404: matrícula não encontrada.
Alterar a situação dos alunos
POST /operational/classes/{class_uuid}/students/change-status
Altera a situação de uma ou mais matrículas da turma. Aceita vários alunos de uma vez. A situação só pode ser alterada com a turma aberta.
Regras, por situação:
- Aprovado: o aluno precisa ter CPF ou passaporte cadastrado.
- Aprovado, Reprovado e Não concluído: a data de término do aluno precisa estar preenchida.
- Aprovado e Reprovado de aluno particular (sem empresa vinculada): os pagamentos já liberados no financeiro precisam somar o valor do treinamento.
- Cancelado de aluno particular: o aluno não pode ter pagamento registrado.
Os alunos que atendem às regras são alterados. Os que não atendem são informados na resposta, com o motivo, e não são alterados.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| students_uuid | Sim | lista de uuids | Matrículas dos alunos na turma (campo uuid da listagem) |
| status_id | Sim | inteiro | Nova situação (identificador obtido em /operational/classes/students/statuses) |
Resposta
- 200:
{"message": "Status alterado com sucesso."}. - 400:
{"errors": ["Aluno ... pagamentos não completos.", ...]}quando algum aluno não pode mudar de situação. Os demais alunos são alterados normalmente. - 400:
{"message": "Não é possível alterar o status de um aluno de uma turma não aberta."}quando a turma não está aberta. - 422: dados inválidos.
Exemplo
curl -X POST https://api.pedagogo.app/operational/classes/<uuid-da-turma>/students/change-status \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token-de-sessao>" \
-d '{
"students_uuid": ["<uuid-da-matricula>"],
"status_id": 1
}'
Lookups de alunos
GET /operational/classes/students
Lista os cadastros de alunos da empresa cliente, para escolher o aluno da matrícula.
Parâmetros de URL
| Parâmetro | Descrição |
|---|---|
| search | Busca no nome, no documento, no celular, no e-mail e no uuid do cadastro |
| mt | Marcação do aluno no cadastro (valor exato) |
| customer_vendor_business_id | Empresa do aluno (identificador numérico) |
| customer_vendor_business | Nome ou razão social da empresa |
| columnName | Coluna de ordenação, com orderData |
| orderData | Sentido da ordenação: asc ou desc |
| per_page | Quantidade por página |
| page | Número da página, com per_page |
Resposta: lista de cadastros de alunos, com uuid do cadastro, nome, documento, contatos, empresa vinculada e demais dados do cadastro.
GET /operational/classes/students/responsible
Lista os usuários da empresa cliente, para escolher o responsável pelo aluno.
GET /operational/classes/students/agent
Lista os usuários da empresa cliente, para escolher o agente do aluno. Esta rota executa a mesma listagem de usuários da rota de responsável.
Parâmetros de URL (para as duas rotas)
| Parâmetro | Descrição |
|---|---|
| search | Busca no nome, no e-mail e no celular do usuário |
| columnName | Coluna de ordenação, com orderData |
| orderData | Sentido da ordenação: asc ou desc |
| per_page | Quantidade por página |
| page | Número da página, com per_page |
Resposta: lista de usuários, com id, name, email e os demais dados do cadastro do usuário.
GET /operational/classes/students/statuses
Lista as situações do aluno na turma.
Parâmetros de URL: per_page e page.
Resposta: lista de situações, com id e status. Use o id em status_id ao alterar a situação.
Exemplo
curl "https://api.pedagogo.app/operational/classes/students/statuses" \
-H "Accept: application/json" \
-H "Authorization: Bearer <token-de-sessao>"