Turmas

Turmas de uma disciplina: cadastro, período, equipe auxiliar e prontidão.

Lista as turmas de uma disciplina

GET /disciplinas/{disciplinaId}/turmas

Acesso: Exige a capacidade LER, em algum escopo (a resposta traz só o que a pessoa pode ver). Status de sucesso: 200.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Restrições	Descrição
`disciplinaId`	`string (uuid)`	sim		Id da disciplina.

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Restrições	Descrição
`busca`	`string`	não	a 100 caracteres	Texto para buscar (nome ou e-mail, conforme a rota).
`limite`	`integer`	não	1…200; padrão: `50`	Quantos itens por página (1 a 200; o padrão varia por rota, em geral 50).
`deslocamento`	`integer`	não	0…100000; padrão: `0`	Quantos itens pular, para paginar (até 100000).
`inativos`	`"true"` \| `"false"`	não	padrão: `"false"`	`true` inclui também os registros inativos.

Resposta

lista de TurmaDto (+ total)

Campo	Tipo	Obrigatório
`id`	`string (uuid)`	sim
`disciplinaId`	`string (uuid)`	sim
`instituicaoId`	`string (uuid)`	sim
`nome`	`string`	sim
`ativo`	`boolean`	sim
`endereco`	`string` ou `nulo`	sim
`localAtividade`	`string` ou `nulo`	sim
`lat`	`number` ou `nulo`	sim
`lng`	`number` ou `nulo`	sim
`toleranciaAntesMin`	`integer` ou `nulo`	sim
`toleranciaDepoisMin`	`integer` ou `nulo`	sim
`notasVisiveisEm`	Data ou `nulo`	sim
`dataInicio`	Data ou `nulo`	sim
`dataFim`	Data ou `nulo`	sim

Em caso de erro: modelo ErroApi.

Exemplo

bash

curl -X GET "$API/disciplinas/{disciplinaId}/turmas" -H "Authorization: Bearer $TOKEN"

Cria uma turma na disciplina

POST /disciplinas/{disciplinaId}/turmas

Não é idempotente: uma turma não tem identificador único, então repetir a chamada cria outra turma.

Acesso: Exige a capacidade CADASTRAR sobre disciplina (params.disciplinaId). Status de sucesso: 201.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Restrições	Descrição
`disciplinaId`	`string (uuid)`	sim		Id da disciplina.

Corpo da requisição (TurmaCriar)

Campo	Tipo	Obrigatório	Restrições
`nome`	`string`	sim	1–200 caracteres
`endereco`	`string` ou `nulo`	não	a 500 caracteres
`localAtividade`	`string` ou `nulo`	não	a 500 caracteres
`lat`	`number` ou `nulo`	não	-90…90
`lng`	`number` ou `nulo`	não	-180…180
`toleranciaAntesMin`	`integer` ou `nulo`	não	0…720
`toleranciaDepoisMin`	`integer` ou `nulo`	não	0…720
`notasVisiveisEm`	Data ou `nulo`	não

Resposta

TurmaDto

Campo	Tipo	Obrigatório
`id`	`string (uuid)`	sim
`disciplinaId`	`string (uuid)`	sim
`instituicaoId`	`string (uuid)`	sim
`nome`	`string`	sim
`ativo`	`boolean`	sim
`endereco`	`string` ou `nulo`	sim
`localAtividade`	`string` ou `nulo`	sim
`lat`	`number` ou `nulo`	sim
`lng`	`number` ou `nulo`	sim
`toleranciaAntesMin`	`integer` ou `nulo`	sim
`toleranciaDepoisMin`	`integer` ou `nulo`	sim
`notasVisiveisEm`	Data ou `nulo`	sim
`dataInicio`	Data ou `nulo`	sim
`dataFim`	Data ou `nulo`	sim

Em caso de erro: modelo ErroApi.

Exemplo

bash

curl -X POST "$API/disciplinas/{disciplinaId}/turmas" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"nome":"texto"}'

Lista as turmas que a pessoa enxerga

GET /turmas

Acesso: Exige a capacidade LER, em algum escopo (a resposta traz só o que a pessoa pode ver). Status de sucesso: 200.

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Restrições	Descrição
`busca`	`string`	não	a 100 caracteres	Texto para buscar (nome ou e-mail, conforme a rota).
`limite`	`integer`	não	1…200; padrão: `50`	Quantos itens por página (1 a 200; o padrão varia por rota, em geral 50).
`deslocamento`	`integer`	não	0…100000; padrão: `0`	Quantos itens pular, para paginar (até 100000).
`inativos`	`"true"` \| `"false"`	não	padrão: `"false"`	`true` inclui também os registros inativos.
`disciplinaId`	`string (uuid)`	não		Id da disciplina.

Resposta

lista de TurmaDto (+ total)

Campo	Tipo	Obrigatório
`id`	`string (uuid)`	sim
`disciplinaId`	`string (uuid)`	sim
`instituicaoId`	`string (uuid)`	sim
`nome`	`string`	sim
`ativo`	`boolean`	sim
`endereco`	`string` ou `nulo`	sim
`localAtividade`	`string` ou `nulo`	sim
`lat`	`number` ou `nulo`	sim
`lng`	`number` ou `nulo`	sim
`toleranciaAntesMin`	`integer` ou `nulo`	sim
`toleranciaDepoisMin`	`integer` ou `nulo`	sim
`notasVisiveisEm`	Data ou `nulo`	sim
`dataInicio`	Data ou `nulo`	sim
`dataFim`	Data ou `nulo`	sim

Em caso de erro: modelo ErroApi.

Exemplo

bash

curl -X GET "$API/turmas" -H "Authorization: Bearer $TOKEN"

Lê uma turma

GET /turmas/{turmaId}

Acesso: Exige a capacidade LER sobre turma (params.turmaId). Status de sucesso: 200.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Restrições	Descrição
`turmaId`	`string (uuid)`	sim		Id da turma.

Resposta

TurmaDto

Campo	Tipo	Obrigatório
`id`	`string (uuid)`	sim
`disciplinaId`	`string (uuid)`	sim
`instituicaoId`	`string (uuid)`	sim
`nome`	`string`	sim
`ativo`	`boolean`	sim
`endereco`	`string` ou `nulo`	sim
`localAtividade`	`string` ou `nulo`	sim
`lat`	`number` ou `nulo`	sim
`lng`	`number` ou `nulo`	sim
`toleranciaAntesMin`	`integer` ou `nulo`	sim
`toleranciaDepoisMin`	`integer` ou `nulo`	sim
`notasVisiveisEm`	Data ou `nulo`	sim
`dataInicio`	Data ou `nulo`	sim
`dataFim`	Data ou `nulo`	sim

Em caso de erro: modelo ErroApi.

Exemplo

bash

curl -X GET "$API/turmas/{turmaId}" -H "Authorization: Bearer $TOKEN"

Atualiza uma turma

PATCH /turmas/{turmaId}

Acesso: Exige a capacidade CADASTRAR sobre turma (params.turmaId). Status de sucesso: 200.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Restrições	Descrição
`turmaId`	`string (uuid)`	sim		Id da turma.

Corpo da requisição (TurmaAtualizar)

Campo	Tipo	Obrigatório	Restrições
`nome`	`string`	não	1–200 caracteres
`endereco`	`string` ou `nulo`	não	a 500 caracteres
`localAtividade`	`string` ou `nulo`	não	a 500 caracteres
`lat`	`number` ou `nulo`	não	-90…90
`lng`	`number` ou `nulo`	não	-180…180
`toleranciaAntesMin`	`integer` ou `nulo`	não	0…720
`toleranciaDepoisMin`	`integer` ou `nulo`	não	0…720
`notasVisiveisEm`	Data ou `nulo`	não
`ativo`	`boolean`	não

Resposta

TurmaDto

Campo	Tipo	Obrigatório
`id`	`string (uuid)`	sim
`disciplinaId`	`string (uuid)`	sim
`instituicaoId`	`string (uuid)`	sim
`nome`	`string`	sim
`ativo`	`boolean`	sim
`endereco`	`string` ou `nulo`	sim
`localAtividade`	`string` ou `nulo`	sim
`lat`	`number` ou `nulo`	sim
`lng`	`number` ou `nulo`	sim
`toleranciaAntesMin`	`integer` ou `nulo`	sim
`toleranciaDepoisMin`	`integer` ou `nulo`	sim
`notasVisiveisEm`	Data ou `nulo`	sim
`dataInicio`	Data ou `nulo`	sim
`dataFim`	Data ou `nulo`	sim

Em caso de erro: modelo ErroApi.

Exemplo

bash

curl -X PATCH "$API/turmas/{turmaId}" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'

Lista os auxiliares da turma

GET /turmas/{turmaId}/auxiliares

Acesso: Exige a capacidade LER sobre turma (params.turmaId). Status de sucesso: 200.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Restrições	Descrição
`turmaId`	`string (uuid)`	sim		Id da turma.

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Restrições	Descrição
`busca`	`string`	não	a 100 caracteres	Texto para buscar (nome ou e-mail, conforme a rota).
`limite`	`integer`	não	1…200; padrão: `50`	Quantos itens por página (1 a 200; o padrão varia por rota, em geral 50).
`deslocamento`	`integer`	não	0…100000; padrão: `0`	Quantos itens pular, para paginar (até 100000).
`inativos`	`"true"` \| `"false"`	não	padrão: `"false"`	`true` inclui também os registros inativos.

Resposta

lista de VinculoItem (+ total)

Campo	Tipo	Obrigatório
`id`	`string (uuid)`	sim
`usuarioId`	`string (uuid)`	sim
`nome`	`string`	sim
`email`	`string`	sim
`papel`	`"ADMIN_PLATAFORMA"` \| `"CURADOR"` \| `"PRECEPTOR"` \| `"COORDENADOR"` \| `"PROFESSOR"` \| `"AUXILIAR"`	sim
`instituicaoId`	`string (uuid)` ou `nulo`	sim
`disciplinaId`	`string (uuid)` ou `nulo`	sim
`turmaId`	`string (uuid)` ou `nulo`	sim
`podeAvaliar`	`boolean`	sim
`podeCadastrar`	`boolean`	sim
`ativo`	`boolean`	sim

Em caso de erro: modelo ErroApi.

Exemplo

bash

curl -X GET "$API/turmas/{turmaId}/auxiliares" -H "Authorization: Bearer $TOKEN"

Define o período (início e fim) da turma

PUT /turmas/{turmaId}/periodo

Acesso: Exige a capacidade LER sobre turma (params.turmaId). Status de sucesso: 200.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Restrições	Descrição
`turmaId`	`string (uuid)`	sim		Id da turma.

Corpo da requisição (TurmaPeriodo)

Campo	Tipo	Obrigatório	Restrições	Descrição
`dataInicio`	Data ou `nulo`	sim
`dataFim`	Data ou `nulo`	sim

Resposta

TurmaDto

Campo	Tipo	Obrigatório
`id`	`string (uuid)`	sim
`disciplinaId`	`string (uuid)`	sim
`instituicaoId`	`string (uuid)`	sim
`nome`	`string`	sim
`ativo`	`boolean`	sim
`endereco`	`string` ou `nulo`	sim
`localAtividade`	`string` ou `nulo`	sim
`lat`	`number` ou `nulo`	sim
`lng`	`number` ou `nulo`	sim
`toleranciaAntesMin`	`integer` ou `nulo`	sim
`toleranciaDepoisMin`	`integer` ou `nulo`	sim
`notasVisiveisEm`	Data ou `nulo`	sim
`dataInicio`	Data ou `nulo`	sim
`dataFim`	Data ou `nulo`	sim

Em caso de erro: modelo ErroApi.

Exemplo

bash

curl -X PUT "$API/turmas/{turmaId}/periodo" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"dataInicio":"2026-03-10","dataFim":"2026-03-10"}'

O que já está pronto na turma (contagens)

GET /turmas/{turmaId}/prontidao

Devolve só contagens (alunos com acesso, avaliadores, atividades futuras…), nunca nomes nem e-mails.

Acesso: Exige a capacidade CADASTRAR sobre turma (params.turmaId). Status de sucesso: 200.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Restrições	Descrição
`turmaId`	`string (uuid)`	sim		Id da turma.

Resposta

TurmaProntidao

Campo	Tipo	Obrigatório	Restrições	Descrição
`centro`	`boolean`	sim
`toleranciaPropria`	`boolean`	sim		Tolerância própria da turma; `false` = vale o padrão.
`atividadesFuturas`	`integer`	sim	0…	Atividades não canceladas de hoje em diante (no fuso da instituição).
`alunos`	`integer`	sim	0…
`alunosComAcesso`	`integer`	sim	0…	Alunos que já aceitaram o convite (conta ativa) e conseguem registrar presença.
`avaliadores`	`integer`	sim	0…	Pessoas com conta ativa que podem confirmar presença nesta turma, em qualquer nível (turma, disciplina, instituição).
`avaliadoresConvidados`	`integer`	sim	0…	Pessoas que poderão avaliar, mas ainda não aceitaram o convite.

Em caso de erro: modelo ErroApi.

Exemplo

bash

curl -X GET "$API/turmas/{turmaId}/prontidao" -H "Authorization: Bearer $TOKEN"

Turmas ​

Lista as turmas de uma disciplina ​

Cria uma turma na disciplina ​

Lista as turmas que a pessoa enxerga ​

Lê uma turma ​

Atualiza uma turma ​

Lista os auxiliares da turma ​

Define o período (início e fim) da turma ​

O que já está pronto na turma (contagens) ​

Turmas

Lista as turmas de uma disciplina

Cria uma turma na disciplina

Lista as turmas que a pessoa enxerga

Lê uma turma

Atualiza uma turma

Lista os auxiliares da turma

Define o período (início e fim) da turma

O que já está pronto na turma (contagens)