Paginação

Todas as rotas de listagem da API retornam resultados paginados. A paginação é obrigatória — não é possível recuperar "todos" os registros em uma única requisição (exceto endpoints de exportação).

Parâmetros

Parâmetro	Tipo	Default	Máximo	Descrição
`page`	integer	`1`	1.000.000	Número da página (1-indexed)
`limit`	integer	`10`	`100`	Quantidade de registros por página
`sortBy`	string	varia	—	Campo para ordenação (varia por endpoint)
`sortOrder`	string	`asc`	—	Direção: `asc` ou `desc`

Exemplo

curl "https://api.gdredu.com/v1/students?page=2&limit=20&sortBy=name&sortOrder=desc" \
  -H "Authorization: Bearer gdredu_live_..." \
  -H "x-branch-id: branch-id-aqui"

Formato da resposta

Todas as listas seguem o mesmo envelope:

{
  "data": [
    { "id": "...", "name": "..." },
    { "id": "...", "name": "..." }
  ],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 347,
    "totalPages": 18,
    "hasNext": true,
    "hasPrev": true
  }
}

Campo	Descrição
`data`	Array com os registros da página atual
`pagination.page`	Página atual
`pagination.limit`	Limite usado nesta página
`pagination.total`	Total de registros que correspondem aos filtros
`pagination.totalPages`	Total de páginas (`ceil(total / limit)`)
`pagination.hasNext`	`true` se há uma próxima página
`pagination.hasPrev`	`true` se há uma página anterior

Campos de ordenação (`sortBy`)

Os campos disponíveis para sortBy variam por endpoint. Cada endpoint documenta seus campos válidos. Valores inválidos retornam 400 VALIDATION_ERROR.

Exemplos por recurso

Recurso	Campos de `sortBy`	Default
Estudantes	`name`, `registration`, `class`, `guardian`, `lastPresence`, `createdAt`	`name`
Usuários	`name`, `createdAt`	`name`
Séries	`name`, `createdAt`	`name`
Turmas	`name`, `createdAt`	`name`
Componentes	`name`, `createdAt`	`name`

Erros comuns

`limit` acima do máximo

Se você enviar limit=200 (acima do máximo 100), a API silenciosamente ajusta para 100 em vez de retornar erro. Isso facilita a integração sem quebrar quando limites mudam.

`page` acima do total

Se você solicitar uma página além do total de páginas, data será um array vazio [] e pagination.total mostrará o total real. Verifique hasNext antes de paginar.

Paginação com filtros

Filtros são combinados com paginação. Os filtros reduzem o total, e a paginação navega pelos resultados filtrados:

curl "https://api.gdredu.com/v1/students?gradeId=grade-1&hasGuardian=true&page=1&limit=10" \
  -H "Authorization: Bearer gdredu_live_..." \
  -H "x-branch-id: branch-id-aqui"

Veja a referência de cada endpoint para os filtros disponíveis.