API: relatórios — período, lojas, permissão, totais e limites
A API traz os relatórios do sistema já somados: o mesmo cálculo da tela de relatórios, com os totais do período e a lista dos registros. Serve para alimentar planilhas, painéis e ferramentas de BI sem precisar somar venda por venda.
Os relatórios são só de consulta. Cada um tem a sua seção na documentação da API, com os filtros aceitos e um exemplo de retorno.
Quais relatórios existem
- Cadastros e produtos: clientes, aniversariantes, fornecedores, funcionários, transportadoras e produtos.
- Vendas e ordens de serviço: vendas, produtos vendidos, serviços vendidos, orçamentos, ordens de serviço, devoluções, clientes que mais compram, curva ABC de clientes e de produtos, comissão de vendedores (de vendas e de O.S.), comissão por produto, por serviço e de técnicos, equipamentos de O.S. e tempo por situação das O.S.
- Estoque e compras: estoque, inventário, lotes, compras, produtos comprados, serviços contratados e cotações.
- Financeiro: contas a pagar, contas a receber, extrato, fluxo de caixa, DRE gerencial, saldo das contas bancárias, centro de custo, receitas e despesas por plano de contas, comissão de vendedores sobre o financeiro, movimentações de um cliente, pesquisa de movimentações e envios de cobrança.
- Notas fiscais: NF-e, NFC-e e NFS-e.
- Contratos e locações: contratos de serviço, serviços recorrentes, comissão de contratos, locações por cliente, produtos locados e devolução de produtos locados.
- Atendimentos e agenda: chamados e compromissos.
A lista que vale é a da documentação da sua conta: ela mostra só os módulos do seu produto.
Período
- Informe a data inicial e a final no formato AAAA-MM-DD (por exemplo, 2026-10-01). As duas vão juntas.
- Sem datas, o relatório traz o mês atual.
- O período máximo é de 12 meses. Para um intervalo maior, faça uma consulta para cada pedaço.
- Cada relatório diz na documentação qual data o período filtra (a da venda, a do vencimento, a da emissão…). Alguns relatórios não têm período.
Lojas e permissão
- Sem informar a loja, o relatório soma todas as lojas que o usuário da chave acessa. Para uma loja só, informe a loja.
- O relatório segue a mesma permissão da tela de relatórios. Se o usuário da chave não pode ver aquele relatório no sistema, a API recusa e a mensagem diz qual permissão falta. O relatório de lotes só existe para empresa com o controle de lote ligado.
O que vem na resposta
- Totais: sempre do período inteiro, mesmo quando a lista vem em várias páginas.
- Lista: paginada, com no máximo 100 registros por página.
- Valores vêm como número e datas no formato AAAA-MM-DD.
- O resultado pode ter até 5 minutos: consultas iguais feitas nesse intervalo recebem a mesma resposta.
Quando dá errado
- "O período máximo é de 12 meses. Divida a consulta em períodos menores." — o intervalo passou de 12 meses.
- "... deve estar no formato AAAA-MM-DD" ou "Informe ... juntos" — a data está em outro formato ou foi só uma das duas.
- "Já há um relatório desta chave em execução. Aguarde ele terminar e tente de novo." — cada chave roda um relatório por vez. Espere o anterior terminar.
- "A consulta passou do tempo máximo. Reduza o período ou filtre por loja." — o relatório ficou pesado demais. Diminua o período ou consulte uma loja por vez.
- "O usuário desta chave não tem a permissão ..." — falta ao usuário da chave a permissão do relatório. Quem administra a conta libera nas permissões do usuário.