Gestão de Séries

As séries representam os anos/níveis escolares de uma unidade (ex: "1º Ano Ensino Médio", "6º Ano Fundamental"). Cada série pertence a uma unidade e pode ter múltiplas turmas vinculadas.

:::info
Branch-scoped.
Todos os endpoints de séries exigem contexto de branch. 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/series`	`series:read`	Listar séries (paginado)
POST	`/v1/series`	`series:write`	Criar série
GET	`/v1/series/:id`	`series:read`	Detalhar série
PUT	`/v1/series/:id`	`series:write`	Atualizar série
DELETE	`/v1/series/:id`	`series:write`	Desativar série (soft delete)
POST	`/v1/series/:id/reactivate`	`series:write`	Reativar série

GET /v1/series

Lista as séries 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 letivo ativo da unidade.
`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/series?search=ano&status=active&page=1&limit=10&sortBy=name&sortOrder=asc" \
  -H "Authorization: Bearer gdredu_live_..." \
  -H "x-branch-id: branch-id-aqui"

Resposta (200)

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "1º Ano Ensino Médio",
      "isActive": true,
      "branchId": "a999af34-c399-45f6-9dc9-5e8c024b0a49",
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-01-15T10:00:00.000Z",
      "_count": {
        "classes": 3,
        "students": 87,
        "curriculumDisciplines": 12
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

Campos da resposta

Campo	Tipo	Descrição
`id`	UUID	ID da série
`name`	string	Nome da série
`isActive`	boolean	`true` = ativa, `false` = desativada
`branchId`	UUID	ID da unidade
`createdAt`	ISO 8601	Data de criação
`updatedAt`	ISO 8601	Data da última atualização
`_count.classes`	integer	Número de turmas ativas vinculadas
`_count.students`	integer	Número de estudantes matriculados nas turmas desta série no período letivo
`_count.curriculumDisciplines`	integer	Número de componentes curriculares vinculados à série

POST /v1/series

Cria uma nova série na unidade.

Body

{
  "name": "3º Ano Ensino Médio"
}

Campo	Tipo	Obrigatório	Descrição
`name`	string	sim	Nome da série (1-200 caracteres)

Exemplo

curl -X POST "https://api.gdredu.com/v1/series" \
  -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": "3º Ano Ensino Médio"}'

Resposta (201)

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "name": "3º Ano Ensino Médio",
  "isActive": true,
  "branchId": "a999af34-c399-45f6-9dc9-5e8c024b0a49",
  "createdAt": "2026-06-19T12:00:00.000Z",
  "updatedAt": "2026-06-19T12:00:00.000Z",
  "_count": {
    "classes": 0,
    "students": 0,
    "curriculumDisciplines": 0
  }
}

GET /v1/series/:id

Retorna os detalhes de uma série, incluindo as turmas ativas vinculadas.

Parâmetros (query)

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

Exemplo

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

Resposta (200)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "1º Ano Ensino Médio",
  "isActive": true,
  "branchId": "a999af34-c399-45f6-9dc9-5e8c024b0a49",
  "createdAt": "2026-01-15T10:00:00.000Z",
  "updatedAt": "2026-01-15T10:00:00.000Z",
  "classes": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440000",
      "name": "Turma 1A",
      "type": "REGULAR",
      "shifts": ["MORNING"],
      "daysOfWeek": ["MON", "TUE", "WED", "THU", "FRI"],
      "gradeId": "550e8400-e29b-41d4-a716-446655440000",
      "branchId": "a999af34-c399-45f6-9dc9-5e8c024b0a49",
      "isActive": true,
      "createdAt": "2026-01-20T08:00:00.000Z",
      "updatedAt": "2026-01-20T08:00:00.000Z",
      "_count": {
        "students": 30
      }
    }
  ],
  "_count": {
    "classes": 1,
    "students": 30,
    "curriculumDisciplines": 12
  }
}

Erros

Status	Code	Quando
404	`NOT_FOUND`	Série não existe ou não pertence à unidade da API key

PUT /v1/series/:id

Atualiza o nome de uma série ativa.

Body

{
  "name": "1º Ano Ensino Médio Atualizado"
}

Campo	Tipo	Obrigatório	Descrição
`name`	string	sim	Novo nome (1-200 caracteres)

Exemplo

curl -X PUT "https://api.gdredu.com/v1/series/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": "1º Ano Ensino Médio Atualizado"}'

Resposta (200)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "1º Ano Ensino Médio Atualizado",
  "isActive": true,
  "branchId": "a999af34-c399-45f6-9dc9-5e8c024b0a49",
  "createdAt": "2026-01-15T10:00:00.000Z",
  "updatedAt": "2026-06-19T12:00:00.000Z",
  "_count": {
    "classes": 3,
    "students": 0,
    "curriculumDisciplines": 12
  }
}

Erros

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

DELETE /v1/series/:id

Desativa uma série. A série pode ser reativada posteriormente via POST /v1/series/:id/reactivate.

:::warning
Bloqueio com turmas ativas.
Não é possível desativar uma série que possui turmas ativas vinculadas. Desative ou transfira as turmas primeiro.
:::

Exemplo

curl -X DELETE "https://api.gdredu.com/v1/series/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`	Série não existe, não pertence à unidade, ou já está inativa
400	`CONFLICT`	A série possui turmas ativas vinculadas

POST /v1/series/:id/reactivate

Reativa uma série previamente desativada (isActive: false → isActive: true).

Exemplo

curl -X POST "https://api.gdredu.com/v1/series/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": "Série reativada com sucesso."
}

Erros

Status	Code	Quando
404	`NOT_FOUND`	Série não existe, não pertence à unidade, ou já está ativa