ConceitosPaginação

Paginação

Os endpoints de lista devolvem os resultados em páginas, navegadas por cursor. O formato é o mesmo para empresas, notas, clientes, serviços e guias.

Formato da resposta

GET /v1/nfse?empresa_id=emp_8Kq2mXv41c&limite=2
{  "dados": [    { "id": "nfse_9Lm4tXc2Hb", "status": "processando", "valor": 1800.00 },    { "id": "nfse_3Jt9wPz7Qa", "status": "autorizada", "valor": 1500.00 }  ],  "proximo_cursor": "cur_eyJpZCI6Im5mc2VfM0p0OXdQejdRYSJ9"}

CampoDescrição

  • dados
    Os itens da página, do mais recente para o mais antigo.
  • proximo_cursor
    O cursor da página seguinte. Vem null quando não há mais resultados.

Parâmetros

  • limite
    Padrão
    50
    Descrição
    Itens por página. O padrão, 50, também é o máximo.
  • cursor
    Padrão
    nenhum
    Descrição
    O valor de proximo_cursor recebido na página anterior. Sem ele, a lista começa do item mais recente.

Percorrendo todas as páginas

Repita a chamada passando o cursor recebido até proximo_cursor vir null.

Node.js
async function listarNotas(filtros) {  const notas = [];  let cursor = null;  do {    const query = new URLSearchParams({ ...filtros, ...(cursor && { cursor }) });    const resposta = await fetch(`${BASE}/nfse?${query}`, { headers });    const pagina = await resposta.json();    notas.push(...pagina.dados);    cursor = pagina.proximo_cursor;  } while (cursor);  return notas;}

Por que cursor, e não número de página

Notas são emitidas o tempo todo. Com páginas numeradas, cada item novo empurra os demais, e o seu sistema acaba lendo uma nota duas vezes ou pulando outra. O cursor marca o último item lido, então a leitura continua do ponto certo mesmo com a lista mudando.

Cuidados

  • Trate o cursor como um texto opaco. O formato pode mudar sem aviso.
  • Mantenha os mesmos filtros em todas as páginas. Um cursor usado com filtros diferentes responde 400 com o código cursor_invalido.
  • A resposta não traz o total de itens. Para saber se a lista acabou, olhe só o proximo_cursor.