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
{
  "count": 1500,
  "next": "https://apis.pontotel.com.br/pontotel/api/v4/empregados/?page=2",
  "previous": null,
  "results": [
    { "id": 1, "nome": "João Silva" },
    { "id": 2, "nome": "Maria Santos" }
  ]
}
Campo Tipo Descrição
count integer Total de registros disponíveis (todas as páginas)
next string | null URL da próxima página, null se for a última
previous string | null URL da página anterior, null se for a primeira
results array Registros da página atual

Parâmetros de Paginação

Parâmetro Padrão Máximo Descrição
page 1 - Número da página
page_size 20 100 Registros por página

Exemplos

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

# Página 2 com 50 registros por página
GET /empregados/?page=2&page_size=50

# Máximo de registros por página
GET /empregados/?page_size=100

Iterando Todas as Páginas

Python

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
def listar_todos(url, headers):
    todos = []

    while url:
        response = requests.get(url, headers=headers)
        data = response.json()

        todos.extend(data["results"])
        url = data["next"]  # None quando acabar

        print(f"Carregados: {len(todos)}/{data['count']}")

    return todos

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

JavaScript

JavaScript
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
async function listarTodos(url, headers) {
  const todos = [];

  while (url) {
    const response = await fetch(url, { headers });
    const data = await response.json();

    todos.push(...data.results);
    url = data.next;

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

  return todos;
}

Ordenação

Use o parâmetro ordering para ordenar resultados:

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

# Ordenar por data de admissão (descendente, use -)
GET /empregados/?ordering=-data_admissao

# Múltiplos campos
GET /empregados/?ordering=empregador_id,-data_admissao

Campos Ordenáveis por Entidade

Entidade Campos Ordenáveis
Empregados id, nome, cpf, matricula, data_admissao
Empregadores id, razao_social, cnpj
Marcações id, data_hora
Férias id, data_inicio, data_fim

Boas Práticas

Use page_size adequado

  • Para sincronizações em bulk: use page_size=100
  • Para listagens interativas: use page_size=20 ou page_size=50

Respeite o Rate Limit

Com 1500 empregados e page_size=100, você precisará de 15 requisições. Monitore o rate limit ao iterar muitas páginas.

Próximos Passos