Guia para clientes e desenvolvedores

O SGDAT conectado
às suas próximas
possibilidades.

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.

Analytics A001–A004
Edição de 9 de novembro de 2026
Documento independente, sem dependências externas. Para gerar uma cópia em PDF, use Imprimir → Salvar como PDF no navegador, em papel A4. Desative os cabeçalhos e rodapés automáticos do navegador.
01 · Visão de negócio

Seu sistema de gestão pode ir além da sua própria tela.

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.

Mais visão

Compare vendas por mês, cliente, representante ou produto. Acompanhe recebíveis, compromissos financeiros e estoque.

Mais relacionamento

Enriqueça o CRM com histórico de compras, clientes sem compra e oportunidades de recompra para orientar a equipe comercial.

Mais conexão

Integre catálogos, condições comerciais, envio e acompanhamento de pedidos em aplicações de parceiros.

O valor das rotas Analytics

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.

Comece com uma pergunta que importa para sua empresa.
Quais clientes deixaram de comprar? Como as vendas evoluíram? Onde há estoque próximo do vencimento? Escolha um cenário, habilite as rotas necessárias e valide o resultado com seu parceiro de tecnologia.

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.

02 · Escopo

Duas famílias que se complementam

FamíliaPara que serveExemplos de aplicação
Analytics · A001–A004Consultar cadastros, fatos e agregados comerciais, financeiros e de estoque.BI, indicadores, segmentação de clientes, alertas e apoio à decisão.
Transacional · E001Consultar 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.

SGDAT ⇄ Integra.com ⇄ Backend do integrador ⇄ BI / CRM / Aplicação
RotaDomínio disponívelUso típico
A001Cadastros e referências comerciaisResolver códigos de empresas, clientes, representantes e produtos.
A002Vendas e relacionamento comercialFaturamento, histórico, positivação, recompra e simulação de preço.
A003FinanceiroContas a receber/pagar, boletos, pagamentos e caixa realizado.
A004Estoque, compras e entradasSaldos, vencimentos, reposição, conferências e evolução de custo.
E001Integração comercial por parceiroCatá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.

03 · Primeiros passos

Da credencial à primeira consulta

  1. Obtenha com a equipe de implantação a URL HTTPS do ambiente, as credenciais, as rotas liberadas e o contexto de empresa. Para E001, confirme também o identificador da parceria.
  2. Abra /swagger na URL desse ambiente. Para Axxx, selecione Contrato de Dados A001-A004 v1; para E001, consulte o documento geral.
  3. Autentique pelo backend da integração e armazene o token com acesso restrito.
  4. Faça uma consulta pequena em homologação, confira os códigos e compare o resultado com o mesmo recorte no SGDAT.

Autenticação

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.

Primeira consulta de vendas

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.

Convenções para desenvolver

04 · Conceitos essenciais

Escolha o que medir e o que cada linha representa

ConceitoPerguntaExemplo
Grandeza ou métricaO que quero medir?Valor líquido, quantidade de unidades, número de pedidos.
DimensãoPor 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.
FiltroQuais registros entram na análise?Período, empresas, clientes e produtos selecionados.
OrdenaçãoEm 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.

Como mudar a granularidade em ResumoVendas

agruparPorUma linha representaUso
[]Total do recorte filtradoIndicador geral.
["AnoMes"]Um mêsEvolução mensal.
["AnoMes", "Cliente"]Um cliente em um mêsComparação da carteira.
["AnoMes", "Cliente", "Produto"]Um produto de um cliente em um mêsAnálise do mix comprado.
["Pedido"]Um pedido, com data, cliente e representanteInspeçã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.

Filtrar por empresa não é agrupar por empresa. 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.

As grandezas de vendas

Campo de respostaInterpretação
valorBrutoTotal bruto das mercadorias do recorte.
valorDescontosSoma dos descontos de produto, comercial, repasse e bonificação considerados pela operação.
valorLiquidoValor bruto menos esses descontos. Não é automaticamente o total fiscal da NF-e nem o valor recebido em caixa.
quantidadePedidosPedidos distintos dentro de cada grupo.
quantidadeProdutosVendidosProdutos distintos dentro de cada grupo.
quantidadeUnidadesVendidasSoma 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.

Cuidados ao totalizar

Outros resumos configuráveis

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 / caminhoFinalidade
ResumoContasReceberAté 3: DiaEmissao, SemanaEmissao, AnoMesEmissao, DiaVencimento, SemanaVencimento, AnoMesVencimento, DiaPagamento, SemanaPagamento, AnoMesPagamento, Cliente, Representante, Cidade, Uf, Banco, TipoCobranca, Situacao, PlanoDeVendas.
ResumoContasPagarAté 3: DiaEmissao, SemanaEmissao, AnoMesEmissao, DiaVencimento, SemanaVencimento, AnoMesVencimento, DiaPagamento, SemanaPagamento, AnoMesPagamento, Fornecedor, Situacao.
ResumoFluxoCaixaAté 3: Dia, Semana, AnoMes, Empresa, Conta, Banco, TipoMovimento, Origem.
ResumoEstoqueAté 3: Empresa, Produto, Fornecedor, Marca, Ramo, SituacaoVencimento.
ResumoComprasAté 4: Empresa, Fornecedor, Produto, Marca, Ramo, Dia, Semana, AnoMes, Status, Situacao.
ResumoConferenciasEntradaAté 4: Empresa, Fornecedor, Produto, Marca, Ramo, Dia, Semana, AnoMes, StatusPedido, Situacao, StatusLeitura, StatusNota, StatusEletronico, ConferenciaAsCegas, Divergencia.
ResumoNotasEntradaAté 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.

05 · Receitas de consulta

Da pergunta ao corpo da requisição

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.

Vendas mensais por representante

/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
  }
]

Ranking de produtos por valor vendido

/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: [].

Recebíveis por mês de vencimento e cliente

/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.

Estoque atual por produto e vencimento

/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.

06 · Integração confiável

Paginação, erros e qualidade dos dados

ContextoPaginação de entradaResposta
Consultas paginadas Axxxpage e pageSize na query; início em 1.dados, pageable, number, size, totalElements, last e outros metadados.
Clientes, produtos e planos E001page 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.

Leitura de todas as páginas

pagina = 1
repetir:
    resposta = consultar(filtros_fixos, pagina, tamanho)
    verificar_status_http(resposta)
    processar(resposta.dados)
    se resposta.last == true: encerrar
    pagina = pagina + 1

Mantenha 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.

Tratamento de respostas

HTTPConduta da integração
400Corrigir JSON, tipos ou filtros antes de repetir.
401Verificar credenciais/token e renovar autenticação quando necessário; evitar repetição infinita.
403Revisar liberação da rota, parceria e escopo com o administrador.
404Tratar ausência do recurso, quando prevista no endpoint.
409 em capturaReconciliar a referência externa: existe conteúdo diferente associado a ela.
422 em capturaExibir as inconsistências comerciais, atualizar condições e corrigir o pedido inteiro.
500 / 503Registrar 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.

Aplicação em BI, CRM e automações

08 · Próximos passos

Implante por cenário e valide com o negócio

  1. Defina a entrega: por exemplo, painel mensal de vendas ou pedidos pelo CRM. Relacione os dados e as operações necessários.
  2. Alinhe a contratação: confirme rotas habilitadas, parceiro, empresas, usuários, infraestrutura HTTPS e responsáveis pelo suporte.
  3. Homologue a leitura: valide token, permissões, página vazia, várias páginas, filtros e totais com amostras conhecidas do SGDAT.
  4. Homologue as escritas: teste captura, recusa comercial, reenvio idêntico, conflito e acompanhamento do processamento. Confirme o controle de duplicidade.
  5. Entre em produção: estabeleça frequência de consulta, monitoramento, reconciliação e procedimento de atualização do contrato.

Como usar este guia com o Swagger

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 clienteUso
/swaggerInterface de documentação. Selecione o documento A001–A004 ou o geral para E001.
/swagger/dados-v1/swagger.jsonOpenAPI 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.

Conecte primeiro o cenário de maior valor.
Converse com a Digital Sistemas e com seu parceiro de desenvolvimento para transformar uma necessidade concreta em uma integração homologada. As rotas Analytics podem ser o ponto de partida para ampliar a visão sobre o negócio; a E001 acrescenta o fluxo comercial entre sistemas.