Mais visão
Compare vendas por mês, cliente, representante ou produto. Acompanhe recebíveis, compromissos financeiros e estoque.
Transforme os dados da sua operação em análises, relacionamento com clientes e integrações comerciais com o Integra.com.
Uma camada de APIs para conectar o SGDAT a sistemas de terceiros, com consultas analíticas e operações comerciais orientadas pelas regras do negócio.
Vendas, clientes, produtos, financeiro e estoque já fazem parte da rotina no SGDAT. Com o Integra.com, essas informações podem alimentar outras ferramentas e apoiar decisões nos ambientes em que sua equipe trabalha.
As rotas Analytics oferecem dados detalhados e resumos calculados pela API. Assim, seu parceiro de tecnologia pode desenvolver painéis, acompanhar indicadores e criar ações comerciais usando uma interface documentada, sem precisar conhecer a estrutura interna do banco do SGDAT.
Compare vendas por mês, cliente, representante ou produto. Acompanhe recebíveis, compromissos financeiros e estoque.
Enriqueça o CRM com histórico de compras, clientes sem compra e oportunidades de recompra para orientar a equipe comercial.
Integre catálogos, condições comerciais, envio e acompanhamento de pedidos em aplicações de parceiros.
O integrador escolhe o recorte e o nível de detalhe de uma análise; o Integra.com consulta os dados e calcula os resumos suportados. Isso reduz a necessidade de transportar todos os registros apenas para produzir um indicador e concentra a interpretação das regras na camada do SGDAT.
As mesmas APIs podem atender um BI, um CRM, um portal ou uma automação. Aplicações com IA também podem consumi-las, mas o uso de IA não é requisito para integrar. Os dashboards, aplicativos e assistentes são desenvolvidos ou configurados no projeto de integração.
A contratação, as rotas liberadas, as permissões e a implantação devem ser alinhadas com a Digital Sistemas. Este guia descreve capacidades técnicas; não define preços, pacotes, SLA ou resultados comerciais garantidos.
| Família | Para que serve | Exemplos de aplicação |
|---|---|---|
| Analytics · A001–A004 | Consultar cadastros, fatos e agregados comerciais, financeiros e de estoque. | BI, indicadores, segmentação de clientes, alertas e apoio à decisão. |
| Transacional · E001 | Consultar condições comerciais, receber pré-cadastros e pedidos, acompanhar pedidos e consultar títulos e XMLs. | CRM com pedidos, portais de parceiros e aplicações comerciais. |
A E001 também possui consultas: “transacional” não significa que toda chamada grava dados. As consultas Axxx não enviam pedidos. Escolha a família pela finalidade e pelas permissões contratadas.
| Rota | Domínio disponível | Uso típico |
|---|---|---|
| A001 | Cadastros e referências comerciais | Resolver códigos de empresas, clientes, representantes e produtos. |
| A002 | Vendas e relacionamento comercial | Faturamento, histórico, positivação, recompra e simulação de preço. |
| A003 | Financeiro | Contas a receber/pagar, boletos, pagamentos e caixa realizado. |
| A004 | Estoque, compras e entradas | Saldos, vencimentos, reposição, conferências e evolução de custo. |
| E001 | Integração comercial por parceiro | Catálogo comercial, pré-cadastro, captura e acompanhamento de pedidos. |
O escopo efetivo depende do usuário autenticado, da instalação, das empresas autorizadas e, quando aplicável, dos representantes e da parceria. Enviar um código no filtro não concede acesso a ele.
/swagger na URL desse ambiente. Para Axxx, selecione Contrato de Dados A001-A004 v1; para E001, consulte o documento geral.POST /api/Auth/login, com Content-Type: application/json:
{
"usuario": "USUARIO_DA_INTEGRACAO",
"senha": "SENHA_DA_INTEGRACAO"
}Em caso de sucesso, a resposta contém {"token":"JWT"}. Nas chamadas seguintes, envie Authorization: Bearer JWT. As credenciais e a URL dos exemplos são marcadores; não são acessos válidos. Na E001, a parceria autorizada também é verificada no login.
Exemplo para um terminal com cURL, após definir INTEGRA_URL como a URL base, sem barra final, e INTEGRA_TOKEN com o token recebido:
curl --request POST \
"$INTEGRA_URL/api/A002/ResumoVendas?page=1&pageSize=100" \
--header "Authorization: Bearer $INTEGRA_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"dataInicio": "2026-10-01",
"dataFim": "2026-10-31",
"codigosEmpresas": ["1"],
"agruparPor": ["AnoMes"]
}'Substitua empresa e período por valores autorizados. A consulta usa POST para transportar filtros estruturados; esse POST de consulta não grava um pedido.
yyyy-MM-dd. Preserve seu significado de calendário, sem converter automaticamente para outro dia por fuso horário.| Conceito | Pergunta | Exemplo |
|---|---|---|
| Grandeza ou métrica | O que quero medir? | Valor líquido, quantidade de unidades, número de pedidos. |
| Dimensão | Por qual característica quero separar? | Cliente, produto, representante, mês. |
| Granularidade (grão) | O que representa uma linha? | Um mês; um cliente em um mês; um produto por cliente em um mês. |
| Filtro | Quais registros entram na análise? | Período, empresas, clientes e produtos selecionados. |
| Ordenação | Em que sequência aparecem os grupos? | Maior valor líquido primeiro. |
“Grandeza” e “granularidade” são conceitos, não parâmetros genéricos da API. Nos resumos configuráveis, agruparPor define as dimensões. A operação devolve as métricas previstas no contrato. Em ResumoVendas, metricasAdicionais acrescenta conjuntos de medidas; não substitui as métricas básicas.
| agruparPor | Uma linha representa | Uso |
|---|---|---|
[] | Total do recorte filtrado | Indicador geral. |
["AnoMes"] | Um mês | Evolução mensal. |
["AnoMes", "Cliente"] | Um cliente em um mês | Comparação da carteira. |
["AnoMes", "Cliente", "Produto"] | Um produto de um cliente em um mês | Análise do mix comprado. |
["Pedido"] | Um pedido, com data, cliente e representante | Inspeção de pedidos faturados. |
Em vendas, há no máximo três dimensões. Pedido só pode ser usado sozinho. Os valores aceitos são AnoMes, Pedido, Cliente, Representante, Produto, MarcaProduto, RamoProduto, Fornecedor, Cidade, Uf e CanalVenda.
ResumoVendas aceita codigosEmpresas, mas não aceita Empresa em agruparPor. Para comparar empresas nessa operação, faça consultas com uma empresa por vez. Dia e Semana também não são agrupamentos de vendas disponíveis nessa operação.| Campo de resposta | Interpretação |
|---|---|
valorBruto | Total bruto das mercadorias do recorte. |
valorDescontos | Soma dos descontos de produto, comercial, repasse e bonificação considerados pela operação. |
valorLiquido | Valor bruto menos esses descontos. Não é automaticamente o total fiscal da NF-e nem o valor recebido em caixa. |
quantidadePedidos | Pedidos distintos dentro de cada grupo. |
quantidadeProdutosVendidos | Produtos distintos dentro de cada grupo. |
quantidadeUnidadesVendidas | Soma das quantidades dos itens. Verifique as unidades dos produtos antes de interpretar uma soma de itens heterogêneos. |
Os conjuntos adicionais aceitos são DescontosDetalhados, Comissao, ComissaoAtendente, Impostos, Frete e OutrasDespesas. Por exemplo, Comissao acrescenta valorComissao; Frete acrescenta valorFrete. Os demais campos estão descritos no Swagger.
quantidadePedidos desses grupos pode contar o mesmo pedido mais de uma vez. Consulte novamente sem agrupamento para obter o total distinto.Cada endpoint possui sua própria lista. Em A004 usa-se Marca/Ramo; em vendas, MarcaProduto/RamoProduto. Copiar nomes entre operações pode gerar erro.
| Operação / caminho | Finalidade |
|---|---|
ResumoContasReceber | Até 3: DiaEmissao, SemanaEmissao, AnoMesEmissao, DiaVencimento, SemanaVencimento, AnoMesVencimento, DiaPagamento, SemanaPagamento, AnoMesPagamento, Cliente, Representante, Cidade, Uf, Banco, TipoCobranca, Situacao, PlanoDeVendas. |
ResumoContasPagar | Até 3: DiaEmissao, SemanaEmissao, AnoMesEmissao, DiaVencimento, SemanaVencimento, AnoMesVencimento, DiaPagamento, SemanaPagamento, AnoMesPagamento, Fornecedor, Situacao. |
ResumoFluxoCaixa | Até 3: Dia, Semana, AnoMes, Empresa, Conta, Banco, TipoMovimento, Origem. |
ResumoEstoque | Até 3: Empresa, Produto, Fornecedor, Marca, Ramo, SituacaoVencimento. |
ResumoCompras | Até 4: Empresa, Fornecedor, Produto, Marca, Ramo, Dia, Semana, AnoMes, Status, Situacao. |
ResumoConferenciasEntrada | Até 4: Empresa, Fornecedor, Produto, Marca, Ramo, Dia, Semana, AnoMes, StatusPedido, Situacao, StatusLeitura, StatusNota, StatusEletronico, ConferenciaAsCegas, Divergencia. |
ResumoNotasEntrada | Até 4: Empresa, Fornecedor, Cliente, Pessoa, Produto, Marca, Ramo, Dia, Semana, AnoMes, TipoNota, Finalidade, Cfop, SituacaoTributaria. |
Em contas a receber/pagar, os nove agrupamentos temporais combinam Dia, Semana ou AnoMes com Emissao, Vencimento ou Pagamento. Escolha a data de acordo com o indicador: emissão, compromisso ou realização. ResumoFluxoCaixa representa movimentos realizados, não uma previsão de recebimentos e pagamentos futuros.
Todos os exemplos desta seção são POST, autenticados, com filtros no JSON e ?page=1&pageSize=100 na URL. Os códigos e resultados são ilustrativos. Confirme a disponibilidade na versão instalada.
/api/A002/ResumoVendas. Cada linha corresponde a um representante em um mês.
{
"dataInicio": "2026-01-01",
"dataFim": "2026-10-31",
"codigosEmpresas": ["1"],
"agruparPor": ["AnoMes", "Representante"],
"metricasAdicionais": ["Comissao"]
}Trecho ilustrativo de dados, com campos selecionados; o envelope completo não está reproduzido:
[
{
"anoMes": "2026-10",
"codigoRepresentante": "7",
"nomeRepresentante": "REPRESENTANTE EXEMPLO",
"quantidadePedidos": 40,
"valorBruto": 120000.00,
"valorDescontos": 12000.00,
"valorLiquido": 108000.00,
"valorComissao": 2160.00
}
]/api/A002/ResumoVendas. Para os dez primeiros, use page=1&pageSize=10. Esse ranking é uma seleção dos maiores grupos, não o total das vendas.
{
"dataInicio": "2026-10-01",
"dataFim": "2026-10-31",
"codigosEmpresas": ["1"],
"agruparPor": ["Produto"],
"ordenarPor": "ValorLiquido",
"direcaoOrdenacao": "DESC"
}Para classificar por volume, troque a ordenação para QuantidadeUnidadesVendidas e exiba essa medida. Para obter o total geral do período, faça outra chamada com os mesmos filtros e agruparPor: [].
/api/A003/ResumoContasReceber. O filtro escolhe os títulos por vencimento; o resumo separa cada cliente e mês.
{
"dataVencimentoInicio": "2026-11-01",
"dataVencimentoFim": "2026-11-30",
"dataReferenciaPagamento": "2026-11-09",
"codigosEmpresas": ["1"],
"agruparPor": ["AnoMesVencimento", "Cliente"]
}Use valorSaldoAberto para saldo ainda aberto e valorParaPagamentoHoje para o valor calculado para pagamento na referência informada. A consulta, sem filtro de situação, também pode incluir títulos quitados: valorTitulos não significa “valor ainda a receber”. Os campos de juros, multa e desconto vêm calculados pela API.
/api/A004/ResumoEstoque. Cada linha representa uma combinação de produto e situação de vencimento.
{
"codigosEmpresas": ["1"],
"agruparPor": ["Produto", "SituacaoVencimento"],
"dataReferenciaVencimento": "2026-11-09",
"diasVencimentoProximo": 60
}A resposta inclui quantidadeTotal, quantidadeVencida e quantidadeVencimentoProximo. A data de referência classifica vencimentos sobre o saldo consultado; não reconstrói o estoque naquela data. Para movimentos e conciliação, use ConsultarExtratoEstoque.
| Contexto | Paginação de entrada | Resposta |
|---|---|---|
| Consultas paginadas Axxx | page e pageSize na query; início em 1. | dados, pageable, number, size, totalElements, last e outros metadados. |
| Clientes, produtos e planos E001 | page e size na query; padrão 1 e 50. | dados, number, pageSize, totalPages, numberOfElements, totalElements, last, first, empty. |
Os limites variam por endpoint. ResumoVendas normaliza páginas para no máximo 100 registros. Não aplique esse limite como regra universal. Outras operações E001 devem seguir seu próprio schema.
pagina = 1
repetir:
resposta = consultar(filtros_fixos, pagina, tamanho)
verificar_status_http(resposta)
processar(resposta.dados)
se resposta.last == true: encerrar
pagina = pagina + 1Mantenha filtros, contexto e ordenação iguais durante a carga. Registre a quantidade efetiva carregada e compare com totalElements. O total pode mudar se a base for alterada entre chamadas: paginação não equivale a uma fotografia transacional de toda a extração. Concilie cargas em períodos controlados e trate reprocessamentos sem duplicar registros.
Há exceções: ConsultarUltimaCompraProdutoCliente e ConsultarPedidoFaturado retornam objetos ou 404; SimularPrecoVenda retorna uma simulação. Em ConsultarExtratoEstoque, dados é um objeto e a paginação se refere a dados.movimentos.
| HTTP | Conduta da integração |
|---|---|
| 400 | Corrigir JSON, tipos ou filtros antes de repetir. |
| 401 | Verificar credenciais/token e renovar autenticação quando necessário; evitar repetição infinita. |
| 403 | Revisar liberação da rota, parceria e escopo com o administrador. |
| 404 | Tratar ausência do recurso, quando prevista no endpoint. |
| 409 em captura | Reconciliar a referência externa: existe conteúdo diferente associado a ela. |
| 422 em captura | Exibir as inconsistências comerciais, atualizar condições e corrigir o pedido inteiro. |
| 500 / 503 | Registrar diagnóstico sem segredos; acionar suporte quando persistente. Consultas podem ter tentativas limitadas com espera crescente. Escritas exigem reconciliação/idempotência. |
Não use mensagens de erro livres como códigos de negócio. Quando a operação fornecer códigos estruturados, trate-os conforme seu contrato. O conjunto de respostas não é idêntico em todos os endpoints.
Este catálogo identifica os caminhos implementados no código revisado para esta edição. O Swagger do ambiente confirma os campos obrigatórios, opções, respostas e disponibilidade da versão implantada. Caminhos abaixo são relativos à URL base; os Axxx usam POST.
| Operação / caminho | Finalidade |
|---|---|
/api/A001/ConsultarEmpresas | Empresas disponíveis no escopo. |
/api/A001/ConsultarClientes | Cadastros de clientes. |
/api/A001/ConsultarRepresentantes | Representantes comerciais. |
/api/A001/ConsultarFornecedores | Cadastros de fornecedores. |
/api/A001/ConsultarProdutos | Catálogo de produtos. |
/api/A001/ConsultarEstoque | Saldo de estoque; em A004, detalhe por produto/lote. |
/api/A001/ConsultarPromocoes | Campanhas promocionais. |
/api/A001/ConsultarProdutosEmPromocao | Produtos e condições promocionais. |
/api/A001/ConsultarPlanoDeVendas | Planos e condições de venda. |
| Operação / caminho | Finalidade |
|---|---|
/api/A002/ResumoVendas | Métricas de vendas nos agrupamentos escolhidos. |
/api/A002/ResumoFornecedoresVendas | Indicadores comerciais por fornecedor. |
/api/A002/ConsultarItensVendas | Detalhe dos itens vendidos. |
/api/A002/ConsultarProdutosSemVenda | Produtos sem vendas no recorte. |
/api/A002/ConsultarClientesSemCompra | Clientes sem compras no recorte. |
/api/A002/ConsultarPositivacaoClientesVendedor | Clientes e sua positivação por vendedor. |
/api/A002/ResumoPositivacaoVendedores | Indicadores de positivação por vendedor. |
/api/A002/ConsultarUltimaCompraProdutoCliente | Última compra de um produto pelo cliente. |
/api/A002/ConsultarUltimasComprasProdutoCliente | Histórico recente de compras do produto pelo cliente. |
/api/A002/ConsultarPedidoFaturado | Consulta de um pedido já faturado. |
/api/A002/ConsultarSugestaoCompraCliente | Sugestão de recompra para um cliente. |
/api/A002/ConsultarOportunidadesRecompra | Oportunidades de recompra na carteira. |
/api/A002/ConsultarStatusPedidos | Situação operacional dos pedidos. |
/api/A002/ConsultarOrcamentos | Consulta de orçamentos. |
/api/A002/ConsultarPedidosEmAberto | Pedidos ainda em aberto. |
/api/A002/SimularPrecoVenda | Simulação de condição comercial atual. |
| Operação / caminho | Finalidade |
|---|---|
/api/A003/ConsultarContasReceber | Títulos a receber. |
/api/A003/ResumoContasReceber | Agregados de títulos, saldos e valores calculados. |
/api/A003/ConsultarBoletosReceber | Dados de boletos a receber. |
/api/A003/ConsultarPagamentosPagar | Pagamentos de contas a pagar. |
/api/A003/ResumoContasPagar | Agregados de contas a pagar. |
/api/A003/ConsultarContasPagar | Detalhe de contas a pagar. |
/api/A003/ResumoFluxoCaixa | Movimentação de caixa realizada. |
| Operação / caminho | Finalidade |
|---|---|
/api/A004/ConsultarEstoque | Saldo de estoque; em A004, detalhe por produto/lote. |
/api/A004/ResumoEstoque | Quantidades e vencimentos por agrupamento. |
/api/A004/ConsultarVencimentosProximos | Lotes próximos do vencimento. |
/api/A004/ConsultarExtratoEstoque | Movimentos e conciliação de estoque. |
/api/A004/CalcularSugestaoCompras | Sugestão de reposição do estoque da empresa. |
/api/A004/ConsultarPedidosCompra | Pedidos de compra. |
/api/A004/ConsultarItensPedidosCompra | Itens de pedidos de compra. |
/api/A004/ResumoCompras | Agregados de compras. |
/api/A004/ConsultarConferenciasEntrada | Conferências de entrada. |
/api/A004/ConsultarItensConferenciasEntrada | Itens das conferências de entrada. |
/api/A004/ResumoConferenciasEntrada | Indicadores de conferência e divergência. |
/api/A004/EvolucaoCusto | Série histórica de custos. |
/api/A004/ResumoFornecedoresCompras | Indicadores de compras por fornecedor. |
/api/A004/ConsultarNotasEntrada | Notas de entrada. |
/api/A004/ConsultarItensNotasEntrada | Itens de notas de entrada. |
/api/A004/ResumoNotasEntrada | Agregados de notas de entrada. |
Para operações comerciais, consulte o guia completo E001 - Transacional.
Este guia explica a finalidade, os fluxos e as decisões de integração. O Swagger descreve o contrato detalhado de cada chamada e permite experimentá-la no ambiente autorizado. Use os dois em conjunto.
| Referência no ambiente do cliente | Uso |
|---|---|
/swagger | Interface de documentação. Selecione o documento A001–A004 ou o geral para E001. |
/swagger/dados-v1/swagger.json | OpenAPI de Analytics para inspeção do contrato e ferramentas de desenvolvimento. |
Monte esses endereços sobre a URL HTTPS fornecida na implantação. O documento dados-v1 cobre Analytics; não presume cobertura de E001. A versão documental não aparece no caminho /api/A002/...; valide compatibilidade antes de atualizar a instalação ou um cliente gerado.