Paginação e limites
Paginação, janela máxima de período, limite por página e limites de uso da API Consultiva.
Paginação
As respostas paginadas usam sempre o mesmo envelope:
{
"currentPage": 1,
"totalPages": 3,
"totalItems": 234,
"perPage": 100,
"data": [ /* itens */ ]
}| Campo | Significado |
|---|---|
currentPage | página atual |
totalPages | total de páginas |
totalItems | total de itens encontrados |
perPage | itens por página |
data | itens da página |
Parâmetros
page— número da página (começa em1).perPage— itens por página. Limite máximo: 100.
Como navegar: a página 1 traz os itens 1–100, a página 2 traz 101–200, e assim por diante.
O número de páginas é ceil(totalItems / perPage).
Quando a paginação é opcional vs. obrigatória
- Opt-in (vendas, extrato, lançamentos de caixa, ordens de serviço): envie
pagee/ouperPagepara paginar; sem eles, a resposta é a lista completa. - Sempre paginado: listagens (clientes, funcionários, formas de pagamento —
perPagepadrão30), produtos/estoque (informepage), contas a receber e contas a pagar.
Produtos/estoque exige page
Em GET /produto/estoque/busca é necessário informar page (padrão 1). Sem ele, a busca não
retorna os itens esperados.
Janela máxima de período
Nas consultas por período (vendas, financeiro, ordens de serviço), o intervalo entre
inicio_periodo e fim_periodo é limitado a 180 dias. Intervalos maiores retornam
PERIODO_EXCEDE_LIMITE.
Ampliação da janela
Anteriormente o limite era de ~30 dias; foi ampliado para 180 dias. Para janelas maiores, faça consultas sequenciais (ex.: mês a mês) e agregue os resultados no seu sistema.
Limites de uso (rate limiting)
A API Consultiva não impõe hoje um limite fixo de requisições por minuto/hora no nível da aplicação. Os principais limites práticos a respeitar são:
- Janela de período: máximo de 180 dias por consulta.
- Itens por página: máximo de 100 (
perPage). - Token de uso por requisição: algumas consultas encerram a sessão ao final — reaproveite o token com cautela e refaça a obtenção quando necessário.
Uso responsável
Faça uso justo da API: prefira paginar (em vez de baixar tudo de uma vez), use janelas de período adequadas e evite picos de requisições simultâneas. Para grandes volumes (ex.: cargas de BI), agende as consultas e armazene/atualize incrementalmente do seu lado. Limites de taxa podem ser aplicados no futuro ou em nível de infraestrutura.