---
title: "Paginação"
description: "Paginação por cursor na API do Emissor de Nota: formato da resposta (dados e proximo_cursor), parâmetros limite e cursor e como percorrer todas as páginas."
url: https://docs.emissordenota.com/paginacao
language: pt-BR
---
# 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**

```json
{
  "dados": [
    { "id": "nfse_9Lm4tXc2Hb", "status": "processando", "valor": 1800.00 },
    { "id": "nfse_3Jt9wPz7Qa", "status": "autorizada", "valor": 1500.00 }
  ],
  "proximo_cursor": "cur_eyJpZCI6Im5mc2VfM0p0OXdQejdRYSJ9"
}
```

| Campo | Descriçã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

| Parâmetro | Padrão | Descrição |
| --- | --- | --- |
| limite | 50 | Itens por página. O padrão, 50, também é o máximo. |
| cursor | nenhum | 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**

```javascript
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.
