Anos Letivos

Os anos letivos representam o período em que as matrículas são válidas. Cada unidade tem um único ano letivo ativo por vez, mas pode manter um histórico de anos anteriores para referência e relatórios.

:::info
Por que isso importa
Vários outros recursos exigem um schoolYearId para alocar o registro no tempo correto — especialmente matrículas de alunos em turmas (POST /v1/students com classId exige schoolYearId juntos), períodos acadêmicos (bimestres/trimestres/semestres) e configurações de preço por série. Sem um ano letivo ativo, esses fluxos ficam bloqueados.
:::

Endpoints

GET /v1/school-years

Lista os anos letivos da unidade.

Parâmetros (query)

Exemplo

curl "https://api.gdredu.com/v1/school-years?isActive=true&sortBy=year" \
  -H "Authorization: Bearer gdredu_live_..." \
  -H "x-branch-id: 770e8400-e29b-41d4-a716-446655440000"

Resposta (200)

{
  "data": [
    {
      "id": "aa0e8400-e29b-41d4-a716-446655440000",
      "name": "Ano letivo 2026",
      "year": 2026,
      "startDate": "2026-01-15T12:00:00.000Z",
      "endDate": "2026-12-20T12:00:00.000Z",
      "isActive": true,
      "branchId": "770e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2025-11-01T10:00:00.000Z",
      "updatedAt": "2026-01-10T08:00:00.000Z",
      "_count": {
        "studentClasses": 450,
        "academicPeriods": 12
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 3,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

GET /v1/school-years/active

Retorna o ano letivo atualmente ativo da unidade. Útil para integrações que precisam saber em qual ano estão operando.

Resposta (200)

{
  "active": {
    "id": "aa0e8400-e29b-41d4-a716-446655440000",
    "name": "Ano letivo 2026",
    "year": 2026,
    "startDate": "2026-01-15T12:00:00.000Z",
    "endDate": "2026-12-20T12:00:00.000Z",
    "isActive": true,
    "branchId": "770e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2025-11-01T10:00:00.000Z",
    "updatedAt": "2026-01-10T08:00:00.000Z",
    "_count": { "studentClasses": 450, "academicPeriods": 12 }
  }
}

Se nenhum ano estiver ativo, retorna { "active": null }.

POST /v1/school-years

Cria um novo ano letivo.

Body

{
  "name": "Ano letivo 2026",
  "year": 2026,
  "startDate": "2026-01-15",
  "endDate": "2026-12-20",
  "isActive": true
}

Regras de ativação

• Se a unidade não tem ano letivo ativo e isActive for omitido, o novo ano é criado como ativo automaticamente.
• Se a unidade já tem um ano ativo e você enviar isActive: true, o sistema desativa o anterior e ativa o novo.
• Se você enviar isActive: false (ou omitir quando já existe um ativo), o novo ano é criado inativo e o anterior continua ativo.

Resposta (201)

Mesma forma do GET. isActive reflete o estado final após a operação.

Erros

GET /v1/school-years/:id

Detalha um ano letivo. Retorna os mesmos campos da listagem, incluindo _count.studentClasses e _count.academicPeriods.

Exemplo

curl "https://api.gdredu.com/v1/school-years/aa0e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer gdredu_live_..." \
  -H "x-branch-id: 770e8400-e29b-41d4-a716-446655440000"

Resposta (200)

Mesmo formato de GET /v1/school-years. O objeto vem sem o envelope { data, pagination }.

PUT /v1/school-years/:id

Atualiza nome, ano e datas. Não altera o status de ativação — para isso use POST /:id/activate ou POST /:id/deactivate.

Body

{
  "name": "Ano letivo 2026 (corrigido)",
  "year": 2026,
  "startDate": "2026-02-01",
  "endDate": "2026-12-20"
}

Erros

POST /v1/school-years/:id/activate

Define este ano como o ativo da unidade. Os demais anos ativos são desativados automaticamente. Use quando precisar "rotacionar" o ano letivo (ex: início de 2026).

Resposta (200)

{
  "message": "Ano letivo definido como atual.",
  "schoolYear": {
    "id": "aa0e8400-e29b-41d4-a716-446655440000",
    "name": "Ano letivo 2026",
    "year": 2026,
    "isActive": true,
    ...
  }
}

POST /v1/school-years/:id/deactivate

Desativa o ano letivo (mantém o registro para histórico). Após desativar, a unidade ficará sem ano ativo — recomendado ativar outro na sequência.

Resposta (200)

{
  "id": "aa0e8400-e29b-41d4-a716-446655440000",
  "isActive": false,
  "message": "Ano letivo desativado."
}

Conceitos importantes

Apenas um ano ativo por unidade

Cada unidade tem no máximo um ano letivo com isActive: true por vez. A API garante isso: ao ativar um, todos os outros são desativados na mesma transação.

Relação com outros recursos

Os seguintes recursos dependem de um schoolYearId válido:

• Matrícula de aluno em turma (POST /v1/students com classId) — schoolYearId é obrigatório quando se cria o vínculo StudentClass. Veja a seção Anos Letivos na doc de Estudantes.
• Períodos acadêmicos (bimestres/trimestres/semestres) — cada período é vinculado a um schoolYearId.
• Configurações de preço por série — gradePriceConfig referencia um schoolYearId.
• Provas e exames — Exam referencia um schoolYearId.

Workaround para chamadas que pedem schoolYearId

Quando um endpoint pedir schoolYearId e você não souber qual usar, faça GET /v1/school-years/active para obter o ano letivo corrente. Se não houver ativo, a unidade ainda não foi provisionada corretamente — ative um antes de prosseguir.

Ativação na criação

POST /v1/school-years aceita o campo opcional isActive. Quando omitido, o comportamento é inteligente:

• Se a unidade não tem ano ativo → o novo é criado ativo.
• Se a unidade já tem ano ativo → o novo é criado inativo (sem mexer no atual).

Use POST /:id/activate para trocar o ano ativo a qualquer momento.