---
title: "Paginação de listas no SDK Python da NFE.io"
description: "Percorra listas com auto_paging_iter, next_page e has_more — paginação por índice (1-based) nas NFS-e e por cursor nas empresas, nos clientes síncrono e assíncrono."
source_url: https://nfe.io/docs/desenvolvedores/bibliotecas/python/paginacao/
product: bibliotecas
last_updated: 2026-10-14
tags: ["python", "referencia", "paginacao"]
integration: ["sdk"]
---

# Paginação

As listas devolvem uma **página** com os itens e o que é preciso para buscar a próxima. Há dois
estilos, conforme a API de origem:

| Método | Estilo | Parâmetros | Tamanho da página |
|---|---|---|---|
| `service_invoices.list` | por índice (`OffsetPage`) | `page_index` (começa em **1**), `page_count` | 1 a 50 (padrão 10) |
| `companies.list` | por cursor (`CursorPage`) | `limit`, `starting_after`, `ending_before` | 1 a 50 (padrão 10) |

`certificates.list`, `webhooks.list` e `webhooks.event_types` não são paginados: devolvem uma
`list` comum.

## Percorrer tudo: `auto_paging_iter()`

`auto_paging_iter()` entrega os itens desta página e das seguintes, buscando cada página só quando
precisa:

```python
from nfeio import NfeClient

client = NfeClient()
company_id = "ID_DA_EMPRESA"

page = client.service_invoices.list(company_id, page_count=50, issued_begin="2026-01-01")
for invoice in page.auto_paging_iter():
    print(invoice.id, invoice.flow_status, invoice.services_amount)

for company in client.companies.list(limit=50).auto_paging_iter():
    print(company.id, company["name"])
```

- Iterar a página direto (`for x in page`) percorre **só esta página**.
- Não existe método que carregue todas as páginas na memória de uma vez. Para isso, faça
  `list(page.auto_paging_iter())` consciente do volume.
- A iteração sempre para numa página vazia e levanta `UnexpectedResponseError` se a API devolver a
  mesma página de novo, em vez de entrar em laço infinito.

## Página a página

```python
from nfeio import NfeClient, OffsetPage, ServiceInvoice

client = NfeClient()

page: OffsetPage[ServiceInvoice] | None = client.service_invoices.list(
    "ID_DA_EMPRESA", page_count=20
)
while page is not None:
    print(f"página {page.page_index}: {len(page)} notas")
    for invoice in page.data:
        print(invoice.id)
    page = page.next_page()  # None depois da última
```

| Atributo | O que é |
|---|---|
| `data` | Lista com os itens desta página. |
| `has_more` | Se há uma próxima página. |
| `next_page()` | Busca a próxima página, ou devolve `None`. |
| `last_response` | `status_code`, `headers` e `request_id` da resposta. |
| `page_index`, `page_count` | Só em `OffsetPage`. |
| `limit` | Só em `CursorPage`. |

## NFS-e: paginação por índice

```python
from datetime import date

from nfeio import NfeClient

client = NfeClient()

page = client.service_invoices.list(
    "ID_DA_EMPRESA",
    page_index=1,               # começa em 1
    page_count=50,              # de 1 a 50
    issued_begin=date(2026, 9, 1),
    issued_end="2026-09-30",    # date, datetime ou "AAAA-MM-DD"
)
```

Filtros: `issued_begin`, `issued_end`, `created_begin` e `created_end`. A API não informa o total de
itens, então `has_more` é verdadeiro quando a página veio cheia. No pior caso, isso custa uma
requisição a mais que volta vazia. As páginas seguintes mantêm o `page_count` da primeira.

## Empresas: paginação por cursor

```python
from nfeio import NfeClient

client = NfeClient()

primeira = client.companies.list(limit=25)
ultima_id = primeira.data[-1].id if primeira.data else None

if ultima_id is not None:
    seguinte = client.companies.list(limit=25, starting_after=ultima_id)
    anterior = client.companies.list(limit=25, ending_before=seguinte.data[0].id)
```

`starting_after` e `ending_before` são excludentes. No cursor, `auto_paging_iter()` busca as páginas
seguintes com `limit=50`.

## No cliente assíncrono

`list` é uma corrotina, e `auto_paging_iter()` vira iteração assíncrona:

```python
import asyncio

from nfeio import AsyncNfeClient


async def main() -> None:
    async with AsyncNfeClient() as client:
        page = await client.service_invoices.list("ID_DA_EMPRESA", page_count=50)
        async for invoice in page.auto_paging_iter():
            print(invoice.id)

        proxima = await page.next_page()
        print(proxima)


asyncio.run(main())
```