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:

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

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

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

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:

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())