Gestão de Componentes Curriculares

Os componentes curriculares (também chamados de "disciplinas") representam as matérias oferecidas pela instituição — ex: "Matemática", "História", "Biologia". Cada componente pode ter tópicos (subtemas) e ser vinculado a professores que o lecionam em uma unidade específica.

:::info
Escopo institucional
Componentes curriculares são vinculados à instituição (Business), não à unidade. Eles ficam disponíveis para todas as unidades. O vínculo com professores, por outro lado, é por unidade.
:::

Endpoints

Tópicos aninhados

Vínculo com professores

GET /v1/disciplines

Lista os componentes curriculares da instituição com paginação e filtros.

Parâmetros (query)

Exemplo

curl "https://api.gdredu.com/v1/disciplines?includeTopics=true&page=1&limit=10" \
  -H "Authorization: Bearer gdredu_live_..."

Resposta (200)

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Matemática",
      "isActive": true,
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-01-15T10:00:00.000Z",
      "_count": {
        "topics": 5,
        "teachers": 3
      },
      "topics": [
        { "id": "...", "name": "Equações" }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

POST /v1/disciplines

Cria um novo componente curricular na instituição.

Body

{
  "name": "Matemática",
  "topics": [
    { "name": "Equações" },
    { "name": "Geometria Plana" }
  ]
}

Exemplo

curl -X POST "https://api.gdredu.com/v1/disciplines" \
  -H "Authorization: Bearer gdredu_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "name": "Matemática",
    "topics": [{"name": "Equações"}, {"name": "Geometria"}]
  }'

Resposta (201)

Retorna o componente criado com seus tópicos iniciais.

GET /v1/disciplines/:id

Detalha um componente curricular.

Parâmetros (query)

Resposta (200)

Mesma estrutura de POST /v1/disciplines, incluindo opcionalmente topics e teachers.

Erros

PUT /v1/disciplines/:id

Atualiza o nome de um componente curricular ativo.

Body

{
  "name": "Matemática Avançada"
}

DELETE /v1/disciplines/:id

Desativa um componente curricular. Pode ser reativado posteriormente.

POST /v1/disciplines/:id/reactivate

Reativa um componente curricular previamente desativado.

Tópicos

Tópicos são sub-temas de um componente curricular — ex: "Equações" e "Geometria" dentro de "Matemática". Ajudam a organizar questões de prova e conteúdo programático.

GET /v1/disciplines/:id/topics

Lista os tópicos de um componente (ordenados por nome).

{
  "data": [
    { "id": "...", "name": "Equações", "createdAt": "...", "updatedAt": "..." }
  ]
}

POST /v1/disciplines/:id/topics

Cria um novo tópico no componente.

Body: { "name": "Geometria Plana" }

Resposta (201): { "id": "...", "name": "Geometria Plana", "createdAt": "...", "updatedAt": "..." }

PUT /v1/disciplines/:id/topics/:topicId

Atualiza o nome de um tópico.

Body: { "name": "Geometria Plana Avançada" }

DELETE /v1/disciplines/:id/topics/:topicId

Remove um tópico do componente.

Vínculo com Professores

Um professor pode lecionar um componente curricular em uma ou mais unidades. O vínculo é feito por unidade, passando o ID do vínculo do professor com a unidade.

:::info
O que é o teacherId?
É o ID do vínculo do professor com a unidade onde ele leciona. Um professor pode ter diferentes IDs de vínculo em diferentes unidades. Você pode listar os usuários (incluindo seus vínculos) via GET /v1/users.
:::

GET /v1/disciplines/:id/teachers

Lista os professores vinculados ao componente na unidade atual (header x-branch-id).

{
  "data": [
    {
      "userBranchId": "...",
      "userId": "...",
      "name": "Maria Santos",
      "email": "[email protected]"
    }
  ]
}

POST /v1/disciplines/:id/teachers

Vincula professores ao componente na unidade atual. O endpoint é idempotente: se o vínculo já existir, é mantido; se faltar, é criado. Não remove vínculos existentes.

Body:

{
  "teacherIds": ["uuid1", "uuid2"]
}

Todos os teacherIds devem ser vínculos pertencentes à unidade atual. Caso contrário, retorna 400 VALIDATION_ERROR com a lista de IDs inválidos.

DELETE /v1/disciplines/:id/teachers/:teacherBranchId

Desvincula um professor do componente.

Resposta (204): Sem corpo.

Escopo de negócio x escopo de unidade

Endpoints de componente e tópicos não exigem x-branch-id. Endpoints de vínculo de professores exigem x-branch-id para identificar a qual unidade o professor leciona.