Paginação e limites

Paginação das respostas, limites de uso e coleta de períodos completos sem perda de registros.

Resumo dos limites

Limite	Valor
Itens por página (`perPage`)	até 100
Intervalo por consulta	até 180 dias entre `inicio_periodo` e `fim_periodo`
Requisições por minuto	até 60 por loja

Paginação

A paginação utiliza os parâmetros page (número da página, a partir de 1) e perPage (itens por página, até 100):

GET /integracoes/vendas/periodo?empresa=XXXX-XXXX&inicio_periodo=2025-01-01&fim_periodo=2025-06-30&page=1&perPage=100

A resposta paginada tem o seguinte formato:

{
  "currentPage": 1,
  "totalPages": 3,
  "totalItems": 234,
  "perPage": 100,
  "data": [ /* itens da página */ ]
}

Repita a requisição com page=2, page=3 e assim por diante, até que currentPage seja igual a totalPages. Ao final, a quantidade de itens recebidos deve corresponder a totalItems.

Grafia do parâmetro perPage

O parâmetro deve ser escrito exatamente como perPage, com "P" maiúsculo. Outras grafias, como per_page, são desconsideradas sem aviso, e a API aplica o padrão de 10 itens por página.

Comportamento sem `page` e `perPage`

Vendas, extrato, lançamentos de caixa e ordens de serviço retornam todos os registros em uma única resposta, sem paginação.
As demais consultas são sempre paginadas, com tamanho padrão de 10 itens em contas a receber e a pagar, 30 em clientes, funcionários e formas de pagamento, e 100 em produtos.

Recomendamos informar sempre page e perPage=100.

A diferença entre inicio_periodo e fim_periodo pode ser de, no máximo, 180 dias. Intervalos maiores retornam o erro PERIODO_EXCEDE_LIMITE. O limite se aplica às consultas de vendas, financeiro e ordens de serviço.

Período	Diferença	Resultado
2025-01-01 a 2025-06-30	180 dias	aceito
2025-07-01 a 2025-12-28	180 dias	aceito
2025-07-01 a 2025-12-31	183 dias	recusado

Limite de 60 chamadas por minuto

Cada loja pode receber até 60 requisições por minuto nos endpoints /integracoes/*. O limite é contabilizado por loja, e não por usuário: diferentes usuários que consultam a mesma loja compartilham as mesmas 60 requisições. Nos relatórios de toda a rede, que não recebem cnpj nem empresa, o limite é contabilizado por rede.

Todas as respostas trazem os cabeçalhos HTTP X-RateLimit-Limit (limite por minuto) e X-RateLimit-Remaining (requisições ainda disponíveis).

Quando o limite é excedido, a API retorna HTTP 429, com o cabeçalho Retry-After indicando em quantos segundos uma nova requisição será aceita:

{
  "error": true,
  "message": "Limite de 60 requisições por minuto excedido. Aguarde 42 segundo(s) e tente novamente.",
  "data": { "limite": 60, "janela": "minuto", "retry_after": 42 }
}

Aguarde o tempo informado antes de repetir a requisição.

Coleta de períodos completos

Para obter todos os registros de um período extenso, como um ano de vendas para uma ferramenta de BI, siga as etapas abaixo para cada loja:

Divida o período em intervalos de até 180 dias. Para o ano de 2025, por exemplo: 2025-01-01 a 2025-06-30, 2025-07-01 a 2025-12-28 e 2025-12-29 a 2025-12-31.
Consulte a primeira página de cada intervalo, com page=1&perPage=100.
Avance para as páginas seguintes (page=2, page=3 e assim por diante) até que currentPage seja igual a totalPages.
Avance somente após uma resposta HTTP 200. Para os demais códigos, siga a tabela abaixo.
Confira o total: a soma dos itens recebidos em cada intervalo deve corresponder a totalItems.

Tratamento dos códigos de resposta

Código	Significado	Como proceder
`200`	requisição concluída	armazenar os dados e seguir para a próxima página
`400`	parâmetro inválido	corrigir a requisição; o motivo é informado em `error` e `error_info`
`401`	chave de acesso inválida (resposta em texto: `Unauthorized.`)	verificar a chave no cadastro do usuário
`429`	limite de 60 requisições por minuto excedido	aguardar o tempo indicado em `Retry-After` e repetir a mesma página
`500`, `502`, `503` ou falha de conexão	instabilidade temporária	aguardar alguns segundos e repetir a mesma página

Verifique o código de resposta antes de avançar

Se a integração avançar para a página seguinte sem verificar o código de resposta, uma instabilidade temporária pode deixar uma página sem dados, sem que nenhum erro seja registrado.

Cruzamento com outras consultas

Produtos: o id do produto nos itens da venda (itens[].produto.id) é o mesmo utilizado na busca de produtos. Por padrão, a busca retorna somente os produtos ativos; para os inativos, utilize ativo=0&ordenar_por=descricao ou consulte o produto pelo id.
Recebimentos e contas a receber: consulte Vendas, recebimentos e contas a receber.