Gestão de Turmas

As turmas representam os grupos de alunos em um período letivo (ex: "Turma 1A", "Turma do 6º Ano - Tarde"). Cada turma pertence a uma unidade e está vinculada a uma série.

:::info
Todos os endpoints de turmas exigem contexto de unidade. Se sua API key tem escopo BUSINESS, envie o header x-branch-id. Se tem escopo BRANCH, a branch já está embutida na key.
:::

Endpoints

Método	Rota	Scope	Descrição
GET	`/v1/classes`	`classes:read`	Listar turmas (paginado)
POST	`/v1/classes`	`classes:write`	Criar turma
GET	`/v1/classes/:id`	`classes:read`	Detalhar turma
PUT	`/v1/classes/:id`	`classes:write`	Atualizar turma
DELETE	`/v1/classes/:id`	`classes:write`	Desativar turma
POST	`/v1/classes/:id/reactivate`	`classes:write`	Reativar turma

GET /v1/classes

Lista as turmas da unidade com paginação e filtros.

Parâmetros (query)

Parâmetro	Tipo	Default	Descrição
`search`	string	—	Busca por nome (contains, case-insensitive)
`status`	string	`active`	Filtrar por status: `active`, `inactive` ou `all`
`schoolYearId`	UUID	—	ID do período letivo para cálculo do `_count.students`. Se omitido, usa o período ativo da unidade.
`gradeId`	UUID	—	Filtrar por série
`type`	string	—	Filtrar por tipo: `REGULAR`, `TRACK` ou `ELECTIVE`
`page`	integer	`1`	Número da página
`limit`	integer	`10`	Itens por página (máx. 100)
`sortBy`	string	`name`	Campo de ordenação: `name` ou `createdAt`
`sortOrder`	string	`asc`	Direção: `asc` ou `desc`

Exemplo

curl "https://api.gdredu.com/v1/classes?gradeId=grade-id&type=REGULAR&page=1&limit=10" \
  -H "Authorization: Bearer gdredu_live_..." \
  -H "x-branch-id: branch-id-aqui"

Resposta (200)

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Turma 1A",
      "type": "REGULAR",
      "scheduleMode": "BRANCH_DEFAULT",
      "daysOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
      "shifts": ["MORNING"],
      "isActive": true,
      "gradeId": "660e8400-e29b-41d4-a716-446655440000",
      "branchId": "a999af34-c399-45f6-9dc9-5e8c024b0a49",
      "createdAt": "2026-04-28T20:57:59.720Z",
      "updatedAt": "2026-04-28T20:57:59.729Z",
      "grade": {
        "id": "660e8400-e29b-41d4-a716-446655440000",
        "name": "1º Ano Ensino Médio",
        "isActive": true
      },
      "_count": {
        "students": 30
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

Campos da resposta

Campo	Tipo	Descrição
`id`	UUID	ID da turma
`name`	string	Nome da turma
`type`	string	Tipo: `REGULAR` (comum), `TRACK` (itinerário) ou `ELECTIVE` (eletiva)
`scheduleMode`	string	`BRANCH_DEFAULT` (usa horários da unidade) ou `CLASS_SPECIFIC` (horários próprios)
`daysOfWeek`	string[]	Dias da semana: `Sunday`, `Monday`, `Tuesday`, `Wednesday`, `Thursday`, `Friday`, `Saturday`
`shifts`	string[]	Turnos: `MORNING`, `AFTERNOON`, `NIGHT`
`isActive`	boolean	Status (ativa/desativada)
`gradeId`	UUID	ID da série vinculada
`branchId`	UUID	ID da unidade
`grade`	object	Resumo da série (id, name, isActive)
`_count.students`	integer	Número de estudantes no período letivo ativo (ou conforme `schoolYearId`)

POST /v1/classes

Cria uma nova turma na unidade.

Body

{
  "name": "Turma 1A",
  "gradeId": "660e8400-e29b-41d4-a716-446655440000",
  "type": "REGULAR",
  "daysOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
  "shifts": ["MORNING"],
  "scheduleMode": "BRANCH_DEFAULT"
}

Campo	Tipo	Obrigatório	Default	Descrição
`name`	string	sim	—	Nome da turma (1-200 caracteres)
`gradeId`	UUID	sim	—	ID da série (deve existir e estar ativa na mesma unidade)
`type`	string	não	`REGULAR`	`REGULAR`, `TRACK` ou `ELECTIVE`
`daysOfWeek`	string[]	não	Seg-Sex	Dias da semana que a turma funciona
`shifts`	string[]	sim	—	Turnos (ao menos 1; valores: `MORNING`, `AFTERNOON`, `NIGHT`)
`scheduleMode`	string	não	`BRANCH_DEFAULT`	`BRANCH_DEFAULT` ou `CLASS_SPECIFIC`
`overrideBranchPresenceConfig`	boolean	não	`false`	Se `true`, esta turma usará os overrides de presença abaixo em vez dos da unidade
`presenceDedupWindowMinutes`	int?	não	—	Override: janela (1-240 min) para deduplicar presenças consecutivas
`presenceConsiderationWindowMinutes`	int?	não	—	Override: janela de consideração (1-240 min)
`entryEarlyToleranceMinutes`	int?	não	—	Override: tolerância de entrada antecipada (0-240 min)
`entryLateToleranceMinutes`	int?	não	—	Override: tolerância de entrada com atraso (0-240 min)
`exitEarlyToleranceMinutes`	int?	não	—	Override: tolerância de saída antecipada (0-240 min)
`exitLateToleranceMinutes`	int?	não	—	Override: tolerância de saída com atraso (0-240 min)
`notifyAllPresenceEvents`	bool?	não	—	Override: notificar todos os eventos de presença (não só atrasos)

Você também pode passar opcionalmente os campos de override de presença. Veja Override de configuração de presença abaixo.

Exemplo

curl -X POST "https://api.gdredu.com/v1/classes" \
  -H "Authorization: Bearer gdredu_live_..." \
  -H "x-branch-id: branch-id-aqui" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "name": "Turma 1A",
    "gradeId": "660e8400-e29b-41d4-a716-446655440000",
    "shifts": ["MORNING"],
    "daysOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"]
  }'

Resposta (201)

{
  "id": "770e8400-e29b-41d4-a716-446655440000",
  "name": "Turma 1A",
  "type": "REGULAR",
  "scheduleMode": "BRANCH_DEFAULT",
  "daysOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
  "shifts": ["MORNING"],
  "isActive": true,
  "gradeId": "660e8400-e29b-41d4-a716-446655440000",
  "branchId": "a999af34-c399-45f6-9dc9-5e8c024b0a49",
  "createdAt": "2026-06-19T12:00:00.000Z",
  "updatedAt": "2026-06-19T12:00:00.000Z",
  "grade": { "id": "660e8400-e29b-41d4-a716-446655440000", "name": "1º Ano Ensino Médio", "isActive": true },
  "_count": { "students": 0 }
}

Erros

Status	Code	Quando
404	`NOT_FOUND`	Série (`gradeId`) não existe, não pertence à unidade, ou está inativa
400	`VALIDATION_ERROR`	Campos obrigatórios ausentes, `shifts` vazio, ou `type`/`daysOfWeek` com valores inválidos

GET /v1/classes/:id

Retorna os detalhes de uma turma.

Parâmetros (query)

Parâmetro	Tipo	Default	Descrição
`schoolYearId`	UUID	—	ID do período letivo para o cálculo de `_count.students`. Se omitido, usa o período ativo.

Exemplo

curl "https://api.gdredu.com/v1/classes/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer gdredu_live_..." \
  -H "x-branch-id: branch-id-aqui"

Resposta (200)

Mesma estrutura de POST /v1/classes, incluindo grade e _count.students.

Erros

Status	Code	Quando
404	`NOT_FOUND`	Turma não existe, não pertence à unidade, ou a série está inativa

PUT /v1/classes/:id

Atualiza os dados de uma turma ativa.

Body

Mesmos campos de POST /v1/classes, exceto que type é opcional (se omitido, mantém o valor atual).

Campo	Tipo	Obrigatório	Descrição
`name`	string	sim	Novo nome (1-200 caracteres)
`gradeId`	UUID	sim	ID da nova série (deve existir e estar ativa)
`type`	string	não	Se informado, sobrescreve o tipo
`daysOfWeek`	string[]	sim	Substitui a lista de dias
`shifts`	string[]	sim	Substitui a lista de turnos (ao menos 1)
`scheduleMode`	string	não	Se informado, sobrescreve o modo de horários
`overrideBranchPresenceConfig`	boolean	não	Liga/desliga o override de presença da turma
`presenceDedupWindowMinutes`	int?	não	Override: janela (1-240 min) de deduplicação. `null` remove.
`presenceConsiderationWindowMinutes`	int?	não	Override: janela de consideração (1-240 min). `null` remove.
`entryEarlyToleranceMinutes`	int?	não	Override: tolerância de entrada antecipada (0-240 min). `null` remove.
`entryLateToleranceMinutes`	int?	não	Override: tolerância de entrada com atraso (0-240 min). `null` remove.
`exitEarlyToleranceMinutes`	int?	não	Override: tolerância de saída antecipada (0-240 min). `null` remove.
`exitLateToleranceMinutes`	int?	não	Override: tolerância de saída com atraso (0-240 min). `null` remove.
`notifyAllPresenceEvents`	bool?	não	Override: notificar todos os eventos de presença. `null` remove.

Exemplo

curl -X PUT "https://api.gdredu.com/v1/classes/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer gdredu_live_..." \
  -H "x-branch-id: branch-id-aqui" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 660e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "name": "Turma 1A Atualizada",
    "gradeId": "660e8400-e29b-41d4-a716-446655440000",
    "shifts": ["MORNING", "AFTERNOON"],
    "daysOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"]
  }'

Resposta (200)

Mesma estrutura de GET /v1/classes/:id.

Erros

Status	Code	Quando
404	`NOT_FOUND`	Turma não existe, está inativa, ou a série informada está inativa
400	`VALIDATION_ERROR`	`shifts` vazio ou valores inválidos

DELETE /v1/classes/:id

Desativa uma turma. A turma pode ser reativada posteriormente via POST /v1/classes/:id/reactivate.

Exemplo

curl -X DELETE "https://api.gdredu.com/v1/classes/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer gdredu_live_..." \
  -H "x-branch-id: branch-id-aqui"

Resposta (204)

Sem corpo (No Content).

Erros

Status	Code	Quando
404	`NOT_FOUND`	Turma não existe, não pertence à unidade, ou já está inativa

POST /v1/classes/:id/reactivate

Reativa uma turma previamente desativada.

:::note[Pré-requisito]
A série vinculada à turma deve estar ativa (isActive: true) para reativar a turma.
:::

Exemplo

curl -X POST "https://api.gdredu.com/v1/classes/550e8400-e29b-41d4-a716-446655440000/reactivate" \
  -H "Authorization: Bearer gdredu_live_..." \
  -H "x-branch-id: branch-id-aqui"

Resposta (200)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "isActive": true,
  "message": "Turma reativada com sucesso."
}

Erros

Status	Code	Quando
404	`NOT_FOUND`	Turma não existe, já está ativa, ou a série vinculada está inativa

Override de configuração de presença (opcional)

Os endpoints POST /v1/classes e PUT /v1/classes aceitam opcionalmente campos para sobrescrever a configuração de presença da unidade para esta turma específica.

:::info
Quando usar
Use overrides para casos como: turma de educação infantil que precisa de tolerância maior (30 min em vez de 15), turma de ensino integral que precisa de janela de consideração mais ampla, ou turma de reforço que requer notificação de todos os eventos. Para a maioria das turmas, deixe o override desligado e use a configuração da unidade.
:::

Como ativar: envie overrideBranchPresenceConfig: true no body. Quando false (default), os outros campos de override são ignorados.

Campo	Tipo	Faixa	Descrição
`overrideBranchPresenceConfig`	boolean	—	Se `true`, esta turma usará os outros campos abaixo em vez dos valores da unidade
`presenceDedupWindowMinutes`	int \| null	1-240	Janela em minutos para deduplicar presenças consecutivas do mesmo aluno na mesma aula
`presenceConsiderationWindowMinutes`	int \| null	1-240	Janela de consideração para classificar a presença (antes/depois do horário da aula)
`entryEarlyToleranceMinutes`	int \| null	0-240	Tolerância de entrada antecipada — entrada dentro desta janela antes do horário é `ON_TIME`
`entryLateToleranceMinutes`	int \| null	0-240	Tolerância de entrada com atraso — entrada dentro desta janela após o horário é `ON_TIME` (após isso, vira `LATE`)
`exitEarlyToleranceMinutes`	int \| null	0-240	Tolerância de saída antecipada — saída antes do horário é classificada de acordo
`exitLateToleranceMinutes`	int \| null	0-240	Tolerância de saída com atraso — saída após o horário fica `ON_TIME` até esta janela
`notifyAllPresenceEvents`	boolean \| null	—	Se `true`, notifica todos os eventos de presença (não só atrasos) para os responsáveis

Comportamento de null: enviar null em um campo numérico remove o override daquele campo, fazendo a turma usar o valor da unidade. Para manter o override mas apagar o valor, envie 0 (ou outro valor numérico válido). Omitir o campo na requisição não altera o valor atual.

Exemplo com override

{
  "name": "Turma 1A",
  "gradeId": "660e8400-e29b-41d4-a716-446655440000",
  "shifts": ["MORNING"],
  "daysOfWeek": ["Monday", "Wednesday", "Friday"],
  "overrideBranchPresenceConfig": true,
  "presenceDedupWindowMinutes": 10,
  "entryEarlyToleranceMinutes": 10,
  "entryLateToleranceMinutes": 20,
  "exitEarlyToleranceMinutes": 15,
  "notifyAllPresenceEvents": true
}

Removendo um override específico

Para limpar um override (voltar a usar o valor da unidade), envie null no campo:

{
  "name": "Turma 1A",
  "gradeId": "660e8400-e29b-41d4-a716-446655440000",
  "shifts": ["MORNING"],
  "overrideBranchPresenceConfig": true,
  "entryLateToleranceMinutes": null
}

Neste exemplo, a turma continua com override ativado, mas o entryLateToleranceMinutes volta a usar o valor da unidade.

Tipos de turma

Tipo	Valor	Uso
Comum	`REGULAR`	Turmas da Base Nacional Comum Curricular (padrão)
Itinerário Formativo / Trilha	`TRACK`	Turmas de itinerário formativo
Eletiva	`ELECTIVE`	Turmas de disciplinas eletivas

Modos de horário

Modo	Valor	Significado
Padrão da unidade	`BRANCH_DEFAULT`	A turma usa os horários padrão configurados na unidade (padrão)
Horário específico	`CLASS_SPECIFIC`	A turma tem seus próprios horários individuais (mais comum para turmas com rotinas diferenciadas)