Aqui você encontrará informações sobre as requisições disponíveis, os parâmetros necessários para cada requisição e exemplos de uso.
Informações importantes:

• Para acessar as requisições da API, você precisa de um token de autorização.
• A requisição deverá ser feita no formato do GraphQL.
• todas as requisições são realizadas no mesmo endpoint, o que diferencia a informação requisitada é o corpo da requisição.
• Todas as requisições devem ser do tipo POST.

Para acessar as requisições da API, você precisará fornecer um token de autorização. Este token deverá ser enviado no header da requisição, no formato
x-token: seu_token.

Para gerar um token de acesso siga os passos abaixo:

1. Na página do Doma ERP, acesse configurações.
2. Acesse o "Compartilhamento e Acesso a Terceiros" e clique em Criar novo token.
3. Após preencher as informações necessárias, clique em Confirmar.
4. O token criado irá aparecer na listagem.

Nossa API GraphQL utiliza 2 operações principais, são elas:

• Query: utilizada para consultas, ou seja, para buscar informações.
• Mutation: utilizada para criar, alterar ou excluir informações.

O GraphQL também possui um sistema de tipagem, ou seja, cada campo possui um tipo de dado específico, e você pode consultar a documentação para saber quais são esses tipos.

Requisições: A API possui um limite de 25 requisições a cada 5 segundos. Caso esse limite seja ultrapassado, o envio de novas requisições ficará bloqueado por 5 minutos.

Paginação: Consultas que possuem a variável paginação, obrigatoriamente deverá ser preenchida. Caso contrário, o sistema retornará um erro. O limite máximo de registros por página é 200.

Arredondamento fiscal: Para garantir conformidade com NF-e e NFC-e, o sistema calcula o valor total do pedido aplicando o arredondamento por item. Ou seja, cada item deve ter seu total definido como Round(Quantidade × ValorUnitário, 2) e somente depois ser somado para formar o total do pedido.

Dessa forma, o valor informado em PrestacaoPedidoVendaCadastrar.ValorParcela (ou a soma das parcelas) deve ser exatamente igual a esse total já arredondado por item.

Este é o arredondamento fiscal adotado pela SEFAZ; seguimos esse padrão para evitar rejeições na transmissão dos documentos fiscais. O mesmo critério vale para todas as operações comerciais da API em que totais de itens e prestações precisam bater com o documento fiscal.

Exemplo prático:

• Item 1: 8 × 5.443 = 43.544 → 43.54
• Item 2: 3 × 6.538 = 19.614 → 19.61

Total do pedido = 43.54 + 19.61 = 63.15
Prestação = 63.15

Para fazer uma requisição, é necessário enviar um POST, com o conteúdo que deseja consultar no body da requisição.

A requisição da API Doma é composta por 3 partes, a operação, o input e o output.

• Na operação você deve informar o tipo de operação que deseja fazer, podendo ser uma query ou uma mutation.
• O input é o que você deseja de retorno da operação, ele pode ser um ou mais campos da operação, a operação pode ou não ter parâmetros, e esses parâmetros podem ser obrigatórios ou não, na documentação você encontra a informação de quais são os parâmetros obrigatórios.
• O output é o que deseja receber, ele pode ser um ou mais campos, e você pode escolher quais campos deseja receber. Nossas mutations tem um retorno padrão, que é o ID do registro cadastrado.

Aqui está 2 exemplos de requisição, um de uma query(consulta) e outro de uma mutation(criação, alteração ou exclusão).
Exemplo do body de requisição de uma query:

  { 
   "variables":{ 
    "filtro":{ 
     "IdVendedor":6 
    } 
   }, 
   "query":"query 
Metas($filtro: InputFiltroMetas) { 
    metas(Filtro: $filtro) { 
     Id 
     IdVendedor 
     NomeVendedor 
     NomeMeta 
     ValorMeta 
     TipoBonificacao 
     ValorBonificacao 
     Status 
    } 
   }" 
 }  

Exemplo de mutation:

  { 
   "variables":{ 
    "dados":{ 
     "NomeMeta":"Meta Geral", 
     "IdVendedor":null, 
     "ValorMeta":10000, 
     "ValorBonificacao":50, 
     "TipoBonificacao":"VALOR", 
     "Status":"ATIVO" 
    }, 
   }, 
   "query":"mutation 
CadastraMeta($dados: InputCadastrarMeta!) { 
    cadastraMeta(Dados: $dados) 
   }" 
 }  

Exemplo de requisição:

  POST / HTTP/1.1 
 Host: https://api.domagestao.com.br:3000/ 
 Content-Type: application/json 
 x-token: seu_token 
 { 
   "variables":{ 
    "filtro":{ 
     "IdVendedor":6 
    } 
   }, 
   "query":"query 
Metas($filtro: InputFiltroMetas) { 
    metas(Filtro: $filtro) { 
     Id 
     IdVendedor 
     NomeVendedor 
     NomeMeta 
     ValorMeta 
     TipoBonificacao 
     ValorBonificacao 
     Status 
    } 
   }" 
 }  

Uma chamada com sucesso retornará um código 200 e um objeto JSON com os dados solicitados.
Exemplo de retorno:

  { 
   "data": { 
    "metas": [ 
     { 
      "Id": 1, 
      "IdVendedor": null, 
      "NomeVendedor": null, 
      "NomeMeta": "Meta Geral", 
      "ValorMeta": 10000, 
      "TipoBonificacao": "VALOR", 
      "ValorBonificacao": 50, 
      "Status": "ATIVO", 
     }, 
    ] 
   } 
 }  

Nas queries que suportam paginação, caso os parâmetros de paginação não sejam especificados, o sistema retornará por padrão os 10 primeiros registros.

Caso ocorra um erro, a API retornará um código 400 e um objeto JSON com a mensagem de erro.
Exemplo de retorno de erro:

  { 
   "errors": [ 
    { 
     "message": "Mensagem de erro", 
     "field": "campo com erro" 
    } 
   ] 
 }  

Esta seção orienta ferramentas de IA, agentes e integrações automatizadas a consumirem a API de forma eficiente.

Princípio fundamental: sempre que existir uma query analítica ou consolidada que atenda à necessidade, ela deve ser priorizada em relação à consulta de dados brutos. Queries analíticas já aplicam filtros, agrupamentos e cálculos no servidor, reduzindo volume de dados trafegados, processamento desnecessário e impacto no banco de dados.

Queries analíticas disponíveis:

• rankingClientes — Ranking de clientes por volume de vendas. Use quando precisar identificar os melhores compradores, calcular Pareto de faturamento ou segmentar clientes por perfil (gênero, faixa etária, tipo). Evite consultar vendas brutas e agregar manualmente no lado do cliente.
• clientesSemVendas — Lista clientes sem compras faturadas ou entregues no período informado. Use para identificar inatividade comercial. Com ConsiderarPedidosVenda=true, clientes com pedido de venda no período também são excluídos. Evite cruzar clientes + vendas manualmente para essa análise.
• vendasPorProduto — Vendas agrupadas por produto, com ranking, custo e margem de lucro. Use quando precisar de análise de desempenho comercial por item ou categoria. Suporta múltiplos critérios de ranking (maior venda, quantidade, custo, margem, devoluções, ticket médio).
• rankingFornecedores — Ranking de fornecedores por volume de compras. Use quando precisar avaliar o desempenho da cadeia de fornecimento ou concentração de compras por fornecedor. Consolida notas de compra e despesas financeiras.
• comprasPorProduto — Compras agrupadas por produto, com quantidade comprada, estoque atual e ticket médio. Use quando precisar de análise de reposição, giro de estoque ou planejamento de compras. Evite cruzar manualmente notas de compra com saldo de estoque.
• vendasPorGrade — Vendas distribuídas por variação de grade (cor, tamanho), agrupadas por categoria, coleção ou marca. Use quando precisar de análise de mix de produtos por variação. Essencial para planejamento de reposição de itens com grade.
• movimentoProduto — Extrato cronológico de movimentações de estoque de um produto. Use quando precisar consultar entradas e saídas consolidadas por produto, incluindo ajustes de estoque, notas fiscais e vendas. Evite usar apenas movimentosEstoque quando a integração precisar enxergar movimentações fiscais ou comerciais.

Orientação geral: antes de consultar entidades brutas (vendas, lançamentos, notas), verifique se existe uma query analítica que já consolide a informação desejada. O uso de queries consolidadas é a abordagem recomendada para obter indicadores e relatórios.

A API aplica três camadas de proteção contra uso excessivo. Os limites incidem exclusivamente sobre tokens de terceiros (TokenTerceiro); sessões do sistema e tokens internos não são limitados por essas camadas.

Camada 1 — Limite geral

Válido para qualquer requisição autenticada via TokenTerceiro:

• 25 requisições a cada 5 segundos por token.

Camada 2 — Limite de queries de listagem

Aplicado às queries que retornam listas de dados, relatórios e similares:

• 5 requisições por segundo por token.
• 10 requisições a cada 5 segundos por token.

Ambas as janelas são verificadas simultaneamente; a primeira violada já rejeita a requisição.

Camada 3 — Limite agregado por empresa

Agrupa o consumo de todos os tokens que consultam a mesma empresa, protegendo o banco de dados de cargas distribuídas:

• 10 requisições por segundo por empresa.
• 20 requisições a cada 5 segundos por empresa.

Comportamento quando o limite é atingido

A API responde com HTTP 429. O campo retryAfterSeconds indica quantos segundos aguardar antes de tentar novamente. Para o limite por empresa, o código será COMPANY_RATE_LIMIT_EXCEEDED.

Boas práticas para integrações BI/IA

• Use paginação: queries com suporte a Paginacao retornam apenas os registros solicitados. Prefira páginas menores, como 20 a 50 registros, a buscas completas em um único request.
• Evite requisições concorrentes excessivas: múltiplos workers consultando a mesma empresa ao mesmo tempo consomem o limite agregado da Camada 3.
• Aplique cache local: dados de cadastro mudam com baixa frequência. Armazene-os localmente e revalide apenas quando necessário.
• Respeite o campo retryAfterSeconds: ao receber HTTP 429, aguarde o número de segundos indicado antes de reenviar a requisição.
• Prefira queries analíticas: rankingClientes, vendasPorProduto, comprasPorProduto e similares já consolidam dados no servidor.

A partir de agora você verá todas as Querys (consultas) e Mutations disponíveis, navegue pelo menu de acesso para encontrar as operações desejadas.