Conceitos fundamentais

Antes de usar a API, é importante entender três conceitos que aparecem em todos os endpoints: Instituição, Unidade e Identificadores.

Instituição e Unidades

A GDREdu organiza as instituições em dois níveis:

• Instituição — a empresa de ensino (ex: "Colégio Exemplo LTDA"). É o nível mais alto.
• Unidade (também chamada de "escola" ou "filial") — um campus ou unidade física da instituição. Uma instituição pode ter uma ou várias unidades.

Quando você chama a API, a maioria dos endpoints opera no contexto de uma unidade específica. O identificador de unidade (branchId) é exigido em requisições a dados de estudantes, turmas, séries, etc.

Como identificar a unidade nas requisições

Se sua API key tem escopo Instituição (veja Autenticação), você precisa informar em qual unidade quer operar usando o header x-branch-id em cada requisição:

GET /v1/students?search=joao HTTP/1.1
Host: api.gdredu.com
Authorization: Bearer gdredu_live_...
x-branch-id: 550e8400-e29b-41d4-a716-446655440000

Se sua API key tem escopo Unidade específica, o header é dispensável — a key já sabe em qual unidade operar.

:::info
Requisições com x-branch-id que não pertence à instituição da sua key retornam erro 403 BRANCH_SCOPE_MISMATCH. Requisições com x-branch-id apontando para uma branch que não existe retornam 404 INVALID_BRANCH.
:::

Identificadores retornados pela API

A API retorna identificadores (id) em todos os recursos. Esses IDs são UUIDs (formato: 550e8400-e29b-41d4-a716-446655440000) e não contêm informação hierárquica — você não consegue deduzir a unidade ou instituição a partir do ID de um estudante, por exemplo.

Formato dos IDs

IDs de pessoas: global vs. por unidade

Algumas pessoas (estudantes, usuários) podem estar vinculadas a mais de uma unidade da mesma instituição. Para esses casos, a API trabalha com dois tipos de IDs:

• ID de pessoa — identifica a pessoa como um todo. Exemplo: o userId de um responsável.
• ID de vínculo com a unidade — identifica a matrícula ou vínculo profissional em uma unidade específica. Exemplo: o id de um estudante retornado em /v1/students (que corresponde à matrícula dele naquela unidade).

Regra prática para integração: na maioria dos endpoints da API, o parâmetro :id refere-se ao vínculo com a unidade (matrícula ou vínculo profissional), não à pessoa global. Isso porque as operações são sempre feitas no contexto de uma unidade.

Quando a API precisa do ID global da pessoa (por exemplo, para vincular um responsável a um estudante), o endpoint aceita explicitamente o ID global via um campo dedicado, como guardianUserId.

Resumo: o que você precisa saber

Para integrar com a GDREdu via API, você precisa entender:

1. A instituição é o "dono" da sua API key. Todas as requisições operam dentro dela.
2. A maioria dos endpoints opera em uma unidade. Use x-branch-id (se aplicável) para informar qual.
3. IDs são UUIDs opacos. Trate-os como strings; não tente parseá-los.
4. Pessoas podem ter múltiplos vínculos. Use o ID de vínculo (matrícula) para operações em uma unidade, e o ID de pessoa global quando explicitamente solicitado pela API.
5. Valide a resposta de /v1/me no início da integração para confirmar qual é o escopo da sua key e quais scopes ela possui.