Paginação e limites

Listas

Rotas que listam coisas (alunos de uma turma, atividades, usuários...) devolvem:

{ "items": [ { "...": "..." } ], "total": 137 }

total é a quantidade que atende à consulta, não só desta página. Parâmetros de consulta:

Parâmetro	Padrão	Significado
limite	50	Itens por página, de 1 a 200.
deslocamento	0	Quantos itens pular (até 100 000).
busca	—	Texto livre (até 100 caracteres); filtra por nome e campos parecidos, sem diferenciar maiúsculas.
inativos	false	true inclui itens desativados (por padrão só os ativos).

Algumas listas têm filtros extras (por exemplo de e ate, datas AAAA-MM-DD, nas atividades); veja a referência de cada rota.

Para ler tudo, avance deslocamento de limite em limite até deslocamento >= total:

JavaScript

async function todos(caminho, token) {
  const itens = []
  for (let deslocamento = 0, total = Infinity; deslocamento < total; deslocamento += 200) {
    const r = await fetch(`${API}${caminho}?limite=200&deslocamento=${deslocamento}`, { headers: { Authorization: `Bearer ${token}` } })
    if (!r.ok) throw new Error(`HTTP ${r.status}`)
    const pagina = await r.json()
    itens.push(...pagina.items)
    total = pagina.total
  }
  return itens
}

Python

def todos(caminho, token):
    itens, deslocamento, total = [], 0, None
    while total is None or deslocamento < total:
        r = requests.get(f"{API}{caminho}", params={"limite": 200, "deslocamento": deslocamento},
                         headers={"Authorization": f"Bearer {token}"})
        r.raise_for_status()
        pagina = r.json()
        itens += pagina["items"]
        total = pagina["total"]
        deslocamento += 200
    return itens

A ordem é estável entre páginas enquanto os dados não mudam. Se alguém cadastrar ou desativar itens enquanto você lê, uma página pode repetir ou pular um item; para sincronizações, leia a lista inteira e compare no seu lado.

Limites de chamadas

Cada rota tem um limite próprio, por origem (endereço IP), em uma janela de tempo. Passou do limite: 429 RATE_LIMITED, com retryAfterSeg e o cabeçalho Retry-After. O limite aparece em cada operação da referência (campo Limite). Referência rápida:

Tipo de rota	Limite (por origem)
Entrar, renovar e sair	20 por minuto (login), 60 por minuto (refresh, logout)
Importações CSV	20 por minuto
Cadastros em lote (usuários, vínculos, matrículas)	120 por minuto
Consultas de evolução	300 por minuto
Fluxos do aplicativo (presença, QR)	600 por minuto
Recuperar senha, convite e primeiro acesso	5 a 10 por minuto

Rotas sem limite listado não têm um limite próprio, mas trate 429 em qualquer rota. Como o limite é por origem, vários sistemas atrás do mesmo endereço de saída dividem a mesma cota.

Tamanho

• O corpo JSON de uma requisição pode ter até 100 KB; acima disso a resposta é 413 PAYLOAD_TOO_LARGE.
• Importações CSV: até 500 linhas e 90 000 caracteres por arquivo; arquivos maiores devem ser divididos. Veja Sincronizar alunos.