Saltar a contenido

Paginación y ordenación

Formato estándar de lista

Todas las variables de lista (GET /recurso/) retornan datos paginados en formato:

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "itens": [
    { "id": "1d3fc7947bee78a5179720a", "nome": "jornada de trabalho 08h x 18h" },
    { "id": "2a4bc8058cff89b6280831b", "nome": "jornada de trabalho 09h x 18h" }
  ],
  "total": 239,
  "pagina": 0,
  "por_pagina": 10,
  "ordenacao": [],
  "filtros": []
}
Campo Tipo Descripción
itens array Registros de la página actual
total Integer Total de registros disponibles (todas las páginas)
pagina Integer Índice de la página actual (comenza en 0)
por_pagina Integer Cantidad de elementos retornados en esta página
ordenacao array Criterios de ordenación aplicados en la consulta
filtros array Filtros activos en la consulta

Parámetros de paginación

Parámetro Patrón Intervalo Descripción
pagina 0 ≥0 Índice de página (comenza en cero)
por-pagina 10 1 – 1000 Cantidad de registros por página

Ejemplos

HTTP
1
2
3
4
5
6
7
8
# Página 0 com 10 registros (padrão)
GET /jornadas/

# Segunda página (índice 1) com 50 registros
GET /jornadas/?pagina=1&por-pagina=50

# Máximo de registros por página
GET /jornadas/?por-pagina=1000

Iterando todas las páginas

Como la API usa paginación basada en índice, calcule el total de páginas a partir de los campos total y por_pagina.

Python

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
import requests

def listar_todos(url, headers):
    todos = []
    pagina = 0
    por_pagina = 100

    while True:
        response = requests.get(
            url,
            headers=headers,
            params={"pagina": pagina, "por-pagina": por_pagina}
        )
        response.raise_for_status()
        data = response.json()

        todos.extend(data["itens"])
        print(f"Carregados: {len(todos)}/{data['total']}")

        if len(todos) >= data["total"]:
            break

        pagina += 1

    return todos

# Uso
jornadas = listar_todos(
    "https://apis.pontotel.com.br/pontotel/api/v4/jornadas/",
    headers={"Authorization": f"Bearer {token}"}
)

JavaScript

JavaScript
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
async function listarTodos(url, headers) {
  const todos = [];
  let pagina = 0;
  const porPagina = 100;

  while (true) {
    const params = new URLSearchParams({ pagina, 'por-pagina': porPagina });
    const response = await fetch(`${url}?${params}`, { headers });
    const data = await response.json();

    todos.push(...data.itens);
    console.log(`Carregados: ${todos.length}/${data.total}`);

    if (todos.length >= data.total) break;
    pagina++;
  }

  return todos;
}

Ordenación

Usá el parámetro ordenacao Para definir el orden de los resultados. El formato es campo para creciente y -campo Para atrás.

HTTP
1
2
3
4
5
6
7
8
# Ordenar por nome (ascendente)
GET /jornadas/?ordenacao=nome

# Ordenar por data de criação (descendente)
GET /jornadas/?ordenacao=-criadoEm

# Múltiplos critérios
GET /jornadas/?ordenacao=nome&ordenacao=-criadoEm

Buenas prácticas

Elija un por-pagina adecuado

  • Para sincronizaciones en bulk: use por-pagina=1000
  • Para un listado interactivo: use por-pagina=10 o por-pagina=50

Respeite Rate Limit

Con 2.000 registros y por-pagina=100, necesitarás 20 requisiciones. Monitore el rate limit al iterar muchas páginas.

Próximos pasos