Paginación y límites

Listas

Las rutas que listan cosas (alumnos de un grupo, actividades, usuarios...) devuelven:

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

total es la cantidad que cumple la consulta, no solo la de esta página. Parámetros de consulta:

Parámetro	Por defecto	Significado
limite	50	Elementos por página, de 1 a 200.
deslocamento	0	Cuántos elementos saltar (hasta 100 000).
busca	—	Texto libre (hasta 100 caracteres); filtra por nombre y campos parecidos, sin distinguir mayúsculas.
inativos	false	true incluye elementos desactivados (por defecto solo los activos).

Algunas listas tienen filtros extra (por ejemplo de y ate, fechas AAAA-MM-DD, en las actividades); vea la referencia de cada ruta.

Para leer todo, avance deslocamento de limite en limite hasta deslocamento >= total:

JavaScript

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

Python

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

El orden entre páginas es fijo mientras los datos no cambien. Si alguien registra o desactiva elementos mientras usted lee, una página puede repetir u omitir un elemento; para sincronizaciones, lea la lista completa y compare de su lado.

Límites de llamadas

Cada ruta tiene un límite propio, por origen (dirección IP), en una ventana de tiempo. Si lo supera: 429 RATE_LIMITED, con retryAfterSeg y la cabecera Retry-After. El límite aparece en cada operación de la referencia (campo Límite). Referencia rápida:

Tipo de ruta	Límite (por origen)
Entrar, renovar y salir	20 por minuto (login), 60 por minuto (refresh, logout)
Importaciones CSV	20 por minuto
Altas masivas (usuarios, vínculos, matrículas)	120 por minuto
Consultas de evolución	300 por minuto
Flujos de la aplicación (asistencia, QR)	600 por minuto
Recuperar contraseña, invitación y primer acceso	5 a 10 por minuto

Las rutas sin límite listado no tienen un límite propio, pero trate 429 en cualquier ruta. Como el límite es por origen, varios sistemas detrás de la misma dirección de salida comparten la misma cuota.

Tamaño

• El cuerpo JSON de una solicitud puede tener hasta 100 KB; por encima, la respuesta es 413 PAYLOAD_TOO_LARGE.
• Importaciones CSV: hasta 500 líneas y 90 000 caracteres por archivo; los archivos mayores deben dividirse. Vea Sincronizar alumnos.