API para Desenvolvedores GDREdu

URL base

https://api.gdredu.com/v1

Todas as rotas descritas nesta documentação são relativas a esta URL base. Por exemplo, GET /v1/series corresponde a https://api.gdredu.com/v1/series.

O que você pode fazer com a API

Recurso	Descrição
Séries	Criar, listar, atualizar, desativar e reativar séries/anos letivos
Turmas	CRUD completo de turmas, com reativação
Componentes Curriculares	CRUD de disciplinas, tópicos e vínculo de professores
Estudantes	CRUD completo com filtros avançados, vínculo de responsáveis, exportação CSV facial, galeria de fotos (até 10), bloqueio de acesso físico e janela de acesso
Anos Letivos	CRUD de períodos letivos, ativação do ano corrente, vínculo com matrículas
Frequência do Aluno	Lista agregada e detalhe de frequência, com filtros por período/turno/status
Relatórios	Quem anda faltando, chegando atrasado e saindo adiantado
Usuários/Responsáveis	CRUD de usuários staff e responsáveis, com permissões e turnos, filiais, horários de trabalho, disciplinas lecionadas, redefinição de senha e bloqueio de acesso físico
Ponto Eletrônico	Criar ponto manual e listar registros (com filtros por usuário, unidade e período)
Equipamentos	CRUD de totens e câmeras Intelbras, pareamento via QR Code, teste de conexão, sincronização e mapeamento com catracas
Webhooks	Registrar um webhook por escola para receber eventos de reconhecimento facial em tempo real

Como começar

Obtenha uma API key — Um administrador da sua instituição precisa gerar uma API key no painel da GDREdu em Dashboard → API Keys. Veja Autenticação para detalhes do formato.
Escolha o escopo da key — A key pode ser:
- Business (instituição): funciona para todas as escolas/unidades da instituição. Requer o header x-branch-id em endpoints que operam por unidade.
- Branch (unidade específica): vinculada a uma única escola. Não requer x-branch-id.
Selecione os scopes — Cada key tem scopes granulares (ex: students:read, students:write). Veja Scopes.
Faça sua primeira requisição:

curl https://api.gdredu.com/v1/me \
  -H "Authorization: Bearer gdredu_live_sua_api_key_aqui"

Entenda os conceitos — Antes de usar os endpoints, leia Conceitos fundamentais para entender a estrutura da plataforma (instituição → unidades, identificadores usados pela API).

Validação de escopo (proteção contra cross-tenant)

Todos os endpoints com :id validam que o recurso pertence à instituição e/ou unidade da API key antes de retornar ou modificar dados. Tentativas de acessar recursos de outra instituição resultam em 404 NOT_FOUND (mesmo se o recurso existir — não vaza existência).

Regras de escopo aplicadas:

GET/PUT/DELETE /v1/students/:id — o :id é o studentHasBranchId. Validado contra branchId da API key.
GET/PUT/DELETE /v1/users/:id — o :id é o userId global. Validado contra businessId da API key, ou vínculo com a branch atual.
GET /v1/classes/:id, /v1/equipments/:id, /v1/school-years/:id — todos validados contra branchId da API key.
Vínculos aninhados (/v1/users/:id/work-schedules, /v1/equipments/:id/mappings/search, etc.) — validam o recurso-pai antes de processar.
POST /v1/students com guardianUserId ou guardianEmail — só aceita responsáveis da mesma instituição (cross-tenant bloqueado).
Criar/atualizar com IDs externos (branchId, gradeId, schoolYearId, classId, disciplineId, equipmentId, webhookToken em catraca) — todos validados contra o escopo da API key.

:::info[Sobre o 404]
Quando o recurso não pertence à instituição, retornamos 404 NOT_FOUND (e não 403 FORBIDDEN) para evitar vazar a existência do recurso. Esse é o padrão recomendado pelo OWASP API Security Top 10.
:::

Versão da API

A versão atual é v1, indicada pelo prefixo /v1 na URL. Mudanças que quebram compatibilidade (breaking changes) resultarão em uma nova versão (/v2), mantendo a versão anterior funcionando por um período de transição.

Formato de dados

Todas as requisições e respostas usam JSON (Content-Type: application/json), exceto o endpoint de exportação CSV que retorna text/csv.
Datas são strings no formato ISO 8601 (ex: 2026-06-19T12:00:00.000Z).
IDs são strings UUID v4 (ex: 550e8400-e29b-41d4-a716-446655440000).

Próximos passos

Autenticação — Como criar e usar API keys
Conceitos fundamentais — Business vs Branch, IDs e seus significados
Scopes — Permissões granulares
Paginação — Padrão de listas paginadas
Erros — Códigos de erro e formato

Referência completa da API

Para a referência completa e interativa de todos os endpoints (gerada automaticamente a partir do OpenAPI spec), consulte:

Referência da API — Documentação navegável com exemplos de request/response, schemas de cada recurso, e "Try it out" para testar chamadas.