Paginação

A API do FazNota oferece duas formas de paginar listagens. Ambas convivem; em novas integrações, prefira query string.

Forma 1 — Query string (recomendada)

Disponível em todos os endpoints de listagem:

GET /nfe?page=1&page_size=20
GET /nfce?page=2&page_size=50
GET /nfse?page=1&page_size=20&dataInicial=2026-05-01
GET /nffornecedor?page=1&page_size=20
GET /clientes?page=1&page_size=100
GET /produtos?page=1&page_size=100

Parâmetro	Tipo	Default	Limite
`page`	inteiro	`0` (sem paginação)	—
`page_size`	inteiro	`0` (sem paginação)	500 (1000 para clientes/produtos)

Quando ambos são omitidos ou zero, o endpoint retorna o comportamento legado (geralmente os 100 ou 50 registros mais recentes — varia por endpoint).

Exemplo

curl "https://api.mysebr.com.br/nfemyse-v3/rest/nfe?page=1&page_size=20" \
  -H "Authorization: Token $TOKEN"

Forma 2 — Path (legado)

Mantida por compatibilidade com integrações antigas:

GET /nfe/paginacao/{pagina}/{quantidade}
GET /nfce/paginacao/{pagina}/{quantidade}
GET /produtos/paginacao/{pagina}/{quantidade}/{busca}

{pagina} começa em 1. {quantidade} é o tamanho da página.

Em /produtos/paginacao/.../{busca}, use _todos no campo busca para não filtrar.

Exemplo

curl "https://api.mysebr.com.br/nfemyse-v3/rest/nfe/paginacao/1/20" \
  -H "Authorization: Token $TOKEN"

Comparação

Aspecto	Query string	Path (legado)
Sintaxe	`?page=1&page_size=20`	`/paginacao/1/20`
Disponível em	Todos os listings	NFe, NFCe, Produtos
Filtros adicionais	Combina com outras query (ex.: `&dataInicial=...`)	Não
Cache HTTP	Melhor (query é parte do cache key padrão)	Funciona
Recomendação	✅ Novas integrações	Integrações existentes

Limites e capping

O page_size é capado automaticamente em 500 (ou 1000 para clientes/produtos).
Solicitar page_size=99999 resultará em 500/1000 registros, não 99999.
Para downloads em massa, use paginação iterativa, não tente puxar tudo em uma chamada.

Padrão de iteração recomendado

async function listarTudo(token) {
  const todos = [];
  let pagina = 1;
  const tamanho = 100;

  while (true) {
    const res = await fetch(
      `https://api.mysebr.com.br/nfemyse-v3/rest/clientes?page=${pagina}&page_size=${tamanho}`,
      { headers: { Authorization: `Token ${token}` } }
    );
    const json = await res.json();

    if (json.status !== '005' || !Array.isArray(json.data)) break;
    if (json.data.length === 0) break;

    todos.push(...json.data);

    // Se veio menos do que pedimos, é a última página
    if (json.data.length < tamanho) break;

    pagina++;

    // Pequena pausa para não estourar rate limit
    await new Promise((r) => setTimeout(r, 100));
  }

  return todos;
}

Total de páginas

A API do FazNota não retorna total ou page_count atualmente. Pare de paginar quando receber uma página com menos itens que o page_size solicitado, ou um array vazio.

Sincronização incremental

Para sincronizar NFSes (e em breve outros recursos) sem percorrer todo o histórico, use o filtro dataInicial em conjunto com paginação:

curl "https://api.mysebr.com.br/nfemyse-v3/rest/nfse?dataInicial=2026-05-01&page=1&page_size=50" \
  -H "Authorization: Token $TOKEN"

Salve a data da última sincronização e use-a como dataInicial na próxima. Veja o recipe Sincronizar clientes e produtos.