Pular para conteúdo

Paginação e ordenação

Formato padrão de listagem

Todos os endpoints de listagem (GET /recurso/) retornam dados paginados no 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 Descrição
itens array Registros da página atual
total integer Total de registros disponíveis (todas as páginas)
pagina integer Índice da página atual (começa em 0)
por_pagina integer Quantidade de itens retornados nesta página
ordenacao array Critérios de ordenação aplicados na consulta
filtros array Filtros ativos na consulta

Parâmetros de paginação

Parâmetro Padrão Intervalo Descrição
pagina 0 ≥ 0 Índice da página (começa em zero)
por-pagina 10 1 – 1000 Quantidade de registros por página

Exemplos

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 as páginas

Como a API usa paginação baseada em índice, calcule o total de páginas a partir dos campos total e 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;
}

Ordenação

Use o parâmetro ordenacao para definir a ordem dos resultados. O formato é campo para crescente e -campo para decrescente.

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

Boas práticas

Escolha um por-pagina adequado

  • Para sincronizações em bulk: use por-pagina=1000
  • Para listagens interativas: use por-pagina=10 ou por-pagina=50

Respeite o Rate Limit

Com 2.000 registros e por-pagina=100, você precisará de 20 requisições. Monitore o rate limit ao iterar muitas páginas.

Próximos passos