# Paginação na API fiscal > Paginação na API fiscal é a técnica de dividir uma lista grande de resultados, como notas fiscais emitidas, eventos ou empresas cadastradas, em partes menores chamadas páginas. Em vez de devolver milhares de registros de uma só vez, a API entrega blocos controlados, e o sistema cliente pede a próxima parte quando precisar. **Também conhecido como:** Paginação de resultados, Paginação de listagens, Pagination **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** P ## O que é paginação na API fiscal? Paginação é a forma como uma API organiza respostas que contêm muitos itens. Quando um sistema pede, por exemplo, a lista de todas as NF-e emitidas no mês, a API não manda tudo de uma vez: ela envia um primeiro bloco de resultados e informa como buscar o próximo. É parecido com um livro dividido em páginas. Você lê uma página por vez e sabe que existem outras depois dela. Na API, cada página é uma resposta separada, com uma quantidade limitada de registros. ## Para que serve a paginação? A principal função é manter a comunicação rápida e estável. Respostas enormes demoram para ser geradas, consomem muita memória e podem estourar o tempo limite da requisição. Dividindo em páginas, cada chamada fica leve e previsível. Em integrações fiscais isso é especialmente importante, porque uma empresa pode acumular milhares de documentos por dia entre NF-e, NFC-e, NFS-e, CT-e e MDF-e. Sem paginação, uma simples consulta de histórico poderia travar o ERP ou a plataforma de vendas que está fazendo a busca. ## Como funciona a paginação na prática? O sistema cliente faz uma requisição a um endpoint de listagem, geralmente informando quantos itens quer por página por meio de um query parameter, como limit ou page_size. A API devolve os registros daquela página e, junto com eles, informações para continuar: o número da próxima página, um indicador de que há mais resultados ou um cursor. O cliente repete a chamada usando essa informação até que a API indique que não há mais itens. É comum combinar a paginação com filtros, como período de emissão, CNPJ do emitente ou status do documento, para trazer apenas o que interessa. ## Quais são os tipos de paginação mais comuns? Paginação por página ou deslocamento (offset): o cliente pede a página 1, 2, 3 e assim por diante, ou informa quantos itens pular. É simples de entender, mas pode gerar resultados repetidos ou perdidos se novos documentos forem criados enquanto a listagem está sendo percorrida. Paginação por cursor: a API devolve um marcador que aponta para o último item entregue, e o cliente usa esse marcador para pedir os seguintes. É mais estável para listas que mudam com frequência, como documentos sendo emitidos em tempo real, e costuma ter melhor desempenho em grandes volumes. ## Qual a diferença entre paginação e o NSU na distribuição de DF-e? A paginação é uma escolha de quem desenha a API para organizar listagens. Já o NSU é um número sequencial definido pelo ambiente fiscal para controlar quais documentos já foram distribuídos a um interessado. Os dois têm lógica parecida, pois o cliente avança a partir do último ponto lido, mas o NSU segue regras próprias do serviço de distribuição de DF-e. ## Que cuidados tomar ao consumir APIs paginadas? Percorra todas as páginas até o fim indicado pela API, em vez de supor que a primeira resposta contém tudo. Respeite o tamanho máximo de página e o limite de requisições, evitando disparar chamadas em sequência rápida demais. Em caso de falha temporária, use retry com backoff exponencial e retome a partir da última página ou cursor obtido. Também vale usar filtros de data bem definidos e considerar o fuso horário, para não perder documentos emitidos perto da virada do dia. ## Exemplos de Paginação na API fiscal - Um ERP consulta todas as NFS-e emitidas em março, pedindo 100 notas por página, e percorre as páginas seguintes até a API informar que não há mais resultados. - Uma plataforma de marketplace lista os documentos rejeitados de vários CNPJs usando paginação por cursor, para exibir as rejeições em um painel interno sem sobrecarregar o servidor. - Um agente de inteligência artificial conectado via MCP busca as últimas NFC-e de uma loja e solicita a próxima página apenas se o usuário pedir mais resultados. - Uma rotina noturna sincroniza o histórico de eventos fiscais com o banco de dados do cliente, guardando o último cursor recebido para continuar de onde parou na execução seguinte. ## Perguntas frequentes ### Por que a API não devolve todos os documentos de uma vez? Porque respostas muito grandes ficam lentas, consomem muitos recursos e podem falhar por tempo limite. A paginação mantém cada resposta pequena e confiável, tanto para a API quanto para o sistema que consome os dados. ### Como saber que cheguei à última página? A própria resposta da API indica isso, geralmente com um campo informando se há mais resultados, a ausência de próximo cursor ou uma página com menos itens que o tamanho solicitado. Consulte a documentação do endpoint para saber qual sinal é usado. ### Posso escolher quantos itens vêm por página? Normalmente sim, por meio de um parâmetro na query string, desde que respeitado o valor máximo definido pela API. Páginas maiores reduzem o número de chamadas, mas deixam cada resposta mais pesada. ### Paginação por cursor é melhor que por número de página? Para listas que mudam com frequência, como documentos fiscais sendo emitidos continuamente, o cursor costuma ser mais seguro, pois evita itens repetidos ou pulados. A paginação por número é mais simples e funciona bem para consultas estáveis. ## Termos relacionados - [Filtro de documentos fiscais](https://conota.dev/glossario/filtro-de-documentos-fiscais.md) - [Query parameter](https://conota.dev/glossario/query-parameter.md) - [Endpoint de API](https://conota.dev/glossario/endpoint-de-api.md) - [Limite de requisições](https://conota.dev/glossario/limite-de-requisicoes.md) - [Latência da API fiscal](https://conota.dev/glossario/latencia-da-api-fiscal.md) --- Fonte: [Paginação na API fiscal](https://conota.dev/glossario/paginacao-na-api-fiscal/) · Atualizado em 2026-10-22