Skip to content

Pagination and ordering

Default listing format

All listing endpoints (GET /recurso/) return paged data in format:

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": []
}
Field Type Description
itens array Current Page Records
total integer Total available records (all pages)
pagina integer Current page index (start at 0)
por_pagina integer Number of items returned on this page
ordenacao array Sorting criteria applied in the consultation
filtros array Active filters in query

pagination parameters

Parameter Default Range Description
pagina 0 ≥ 0 Page index (start at zero)
por-pagina 10 1 – 1000 Number of records per page

Examples

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

Iterating all pages

As API uses index-based pagination, calculate the total of pages from the fields total and 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;
}

Sorting

Use parameter ordenacao to define the order of results. The format is campo for growing and -campo to decreasing.

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

Good practice

Choose one por-pagina appropriate

  • For bulk syncs: use por-pagina=1000
  • For interactive listings: use por-pagina=10 or por-pagina=50

Respect Rate Limit

With 2,000 records and por-pagina=100You'll need 20 requests. Monitor the rate limit when iterating many pages.

Next Steps