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
{ "dados": [ { "id": "nfse_9Lm4tXc2Hb", "status": "processando", "valor": 1800.00 }, { "id": "nfse_3Jt9wPz7Qa", "status": "autorizada", "valor": 1500.00 } ], "proximo_cursor": "cur_eyJpZCI6Im5mc2VfM0p0OXdQejdRYSJ9"}CampoDescrição
- dadosOs itens da página, do mais recente para o mais antigo.
- proximo_cursorO 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.
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.