Skip to main content
Endpoints de listagem (GET /colaborador, GET /registro-ponto, etc.) paginam resultados via query string. O padrão é idêntico em todos os endpoints públicos da Pontua, então você pode encapsular uma única função de paginação no seu código.

​
Parâmetros

ParâmetroTipoObrigatórioDefaultLimites
paginaintegersim—≥ 0 (zero-indexed)
limiteintegernãovaria por endpoint (geralmente 25)1 – 100
GET /colaborador?pagina=0&limite=100
GET /colaborador?pagina=1&limite=100  ← próxima página
GET /colaborador?pagina=2&limite=100
pagina é zero-indexed: pagina=0 é a primeira página. Não é pagina=1 como em alguns sistemas. Tenha cuidado se sua aplicação faz page = userInput - 1 por hábito.

​
Envelope de resposta

Todas as respostas paginadas usam o mesmo envelope: 
{
  "pagina": 0,
  "limite": 25,
  "totalRegistros": 847,
  "resultados": [
    { /* item 1 */ },
    { /* item 2 */ },
    { /* ... */ }
  ]
}
CampoDescrição
paginaPágina atual (eco do parâmetro enviado)
limiteLimite usado (eco do parâmetro ou default aplicado se omitido)
totalRegistrosTotal de itens em todas as páginas combinadas
resultadosArray com itens desta página

​
Calcular total de páginas

const totalPaginas = Math.ceil(totalRegistros / limite)
const ultimaPagina = totalPaginas - 1  // zero-indexed

​
Iteração completa em 5 linguagens

async function* paginarTodos(client, path, params = {}) {
  let pagina = 0
  const limite = params.limite || 100

  while (true) {
    const data = await client.fetch(
      `${path}?${new URLSearchParams({ ...params, pagina, limite })}`,
    )

    yield* data.resultados

    const totalProcessado = (pagina + 1) * limite
    if (totalProcessado >= data.totalRegistros) return
    pagina++
  }
}

// Uso — async iterator (memory-efficient)
const pontua = new PontuaClient({ token: process.env.PONTUA_API_TOKEN })
for await (const colaborador of paginarTodos(pontua, '/colaborador', { status: 'ATIVO' })) {
  await processar(colaborador)
}

​
Padrão paralelo (mais rápido para datasets grandes)

Se a ordem dos resultados não importa, você pode paralelizar: 
async function paginarParalelo(client, path, params, concurrency = 5) {
  // 1. Pega primeira página para descobrir total
  const primeira = await client.fetch(`${path}?pagina=0&limite=100`)
  const totalPaginas = Math.ceil(primeira.totalRegistros / 100)

  // 2. Dispara páginas restantes em paralelo, controlando concorrência
  const resultados = [...primeira.resultados]
  const paginas = Array.from({ length: totalPaginas - 1 }, (_, i) => i + 1)

  for (let i = 0; i < paginas.length; i += concurrency) {
    const batch = paginas.slice(i, i + concurrency)
    const responses = await Promise.all(
      batch.map((p) => client.fetch(`${path}?pagina=${p}&limite=100`)),
    )
    for (const r of responses) resultados.push(...r.resultados)
  }

  return resultados
}
⚠️ Não exagere na concorrência. Máximo 5 simultâneas por token é seguro hoje. Veja Rate Limits para o roadmap oficial.

​
Gotchas conhecidos

Se dados estão sendo modificados enquanto você itera, podem aparecer duplicatas (item lido em página 1 reaparece na página 3) ou faltar itens. Para datasets que mudam ativamente:
  • Use filtro de período fechado (atualizadoAte=<data passada>) onde aplicável
  • Ou aceite que pode haver pequena inconsistência (ok para dashboards, problemático para auditoria)
Se um colaborador é deletado enquanto você itera, totalRegistros na página 5 pode ser menor que na página 0. Considere isso uma estimativa, não verdade absoluta.
?limite=500 retorna no máximo 100 resultados (cap server-side). Sempre cheque data.limite no response — se não bate com o que enviou, use o real para calcular totalPaginas.

​
Boas práticas

Use limite alto (50–100)

limite=100 é 10x mais eficiente que limite=10. Reduz chamadas e pressão na API.

Filtre antes de paginar

Sempre que possível, use filtros (status=ATIVO, dataInicio=...) antes de paginar. Reduz totalRegistros e tempo total.

Cache `totalRegistros`

Se está apenas paginando um resultado estático (ex.: dashboard), pegue totalRegistros da primeira página e não recalcule.

Streaming > arrays grandes

Em Node/Python/Go, use generators/async iterators para não carregar 100 mil colaboradores em memória.

​
Veja também