Nesta página, apresentamos como utilizar a ferramenta API GraphQL, utilizada para realizar consultas aos dados da sua empresa no ERP MAXIPROD. Com ela, é possível realizar requisições em nosso banco de dados, agilizando a troca de informações do ERP MAXIPROD com outros sistemas.
Com a API GraphQL, você pode:
a) Construir relatórios personalizados com ferramentas como Power BI e Excel.
b) Enviar informações do ERP MAXIPROD para sistemas de terceiros.
Lembre-se: a API GraphQL é apenas para consulta de dados, não permitindo o envio ou atualização de dados para dentro do sistema.
Está página mostra:
- O que é GraphQL?
- Qual a permissão necessária para consumir a API GraphQL?
- Como gerar o token de acesso à API GraphQL?
- Como utilizar a API GraphQL na plataforma Banana Cake Pop?
- Como utilizar a API GraphQL no Postman?
- Como montar uma consulta à API GraphQL no Excel ou Power BI?
- Quais as limitações de paginação da API GraphQL?
O que é GraphQL?
A API GraphQL é uma solução eficiente e flexível para as necessidades de integração de dados, por oferecer uma abordagem inovadora para lidar com consultas, proporcionando controle total sobre os dados que o usuário solicita.
GraphQL é uma linguagem de consulta e um ambiente de execução criado pelo Facebook, projetado para simplificar a interação com APIs de forma mais eficiente do que os métodos tradicionais, como REST. Com o GraphQL, você pode solicitar exatamente os dados que precisa, sem excesso de informações ou solicitações adicionais.
Benefícios da API GraphQL:
- Flexibilidade: especifique os dados que você precisa em uma única consulta, eliminando a necessidade de múltiplas chamadas à API.
- Eficiência: reduza o tráfego de rede e melhore o desempenho da sua aplicação, obtendo apenas os dados necessários.
- Tipagem forte: aproveite a tipagem forte para uma melhor compreensão e validação dos dados, garantindo integridade e consistência.
- Documentação clara: oferecemos uma documentação detalhada para facilitar o uso da API e entender as possibilidades oferecidas pelo GraphQL.
Qual a permissão necessária para consumir a API GraphQL?
Para consumir a API GraphQL, é necessária a permissão “GQL000 – Consumir API GraphQL”. Para adicionar esta permissão, siga os passos abaixo:
1) Se o seu usuário é ADMIN, acesse o menu superior “Roda dentada > Usuários”.
2) Verifique quais são os perfis de acesso do usuário que deve ter a permissão para consumir a API GraphQL. Para isso, clique no ícone do lápis para editar o cadastro do usuário e expanda a seção “Perfis de acesso”.
3) Verifique qual perfil de acesso deve receber a nova permissão, lembrando que, apenas perfis de acesso que não sejam padrões do sistema podem ser editados. Acesse o menu superior “Roda dentada > Perfis de acesso”.
4) Localize o perfil de acesso que deve receber a nova permissão.
a) Se este perfil é padrão do sistema, é necessário duplicá-lo, criando um perfil semelhante, mas, personalizado. Os perfis de acesso padrão não tem os ícones “Excluir” e “Editar”, e podem ser duplicados clicando na opção “Duplicar perfil selecionado”.
b) Na tela de edição do perfil de acesso personalizado, expanda a seção “Permissões” e clique no botão verde “Novo” para incluir a nova permissão. Atualmente, a permissão “GQL000 – Consumir API GraphQL”, não está atribuída nem mesmo ao perfil de acesso padrão ADMIN.
c) Na tela seguinte, selecione a permissão a incluir e clique no botão “Ok”, localizado no canto inferior direito. Para saber mais sobre perfis de acesso e permissões, clique aqui. Lembre-se de que todos os usuários com este perfil de acesso terão a nova permissão.
5) Se o usuário que recebeu a nova permissão estiver logado no sistema, peça para fazer logoff e novo login, para se certificar de que a nova permissão funcione corretamente.
Observação: atualmente em assinantes “Multi-CNPJ” o usuário deve ter a permissão “GQL000 – Consumir API GraphQL” em todas as empresas (CNPJs) cadastrados, para que possa utilizar a API GraphQL.
Como gerar o token de acesso à API GraphQL?
1) Acesse o ERP MAXIPROD através do link https://app.maxiprod.com.br/, e insira as mesmas credenciais (usuário e senha) utilizadas nos demais acessos.
2) A tela do cadastro de usuários será aberta na nova versão do sistema.
3) Na nova tela de usuários, algumas funcionalidades ainda não foram implementadas, como, por exemplo, a edição/exclusão do cadastro de um usuário, mas, já é possível gerar o token de acesso à API GraphQL. Para isso, clique nos três pontinhos na coluna “Ações” e, em seguida, clique na opção “Token de acesso API GraphQL”.
4) Na janela aberta, se o usuário ainda não possui token de acesso gerado, o sistema apresenta a mensagem: “O usuário não possui um token de acesso.” e exibe, logo abaixo, o botão verde “Gerar”. Clique neste botão para gerar o token pela primeira vez.
Observação: para gerar o token de acesso, é necessário que o usuário tenha a permissão “USU009 – Gerenciar tokens de acesso à APIs”. Em assinantes Multi-CNPJs, o sistema verifica se o usuário tem a permissão na empresa logada. Para saber mais sobre permissões, clique aqui.
5) A seguir, é apresentado o token de acesso e, mais abaixo, o botão “Copiar”, que deve ser usado para copiar o token para a área de transferência.
6) A partir do momento em que o token é criado, são exibidos na janela os botões “Recriar” e “Revogar”. O botão “Recriar” cria um novo token, sobrescrevendo o anterior, enquanto o botão “Revogar” cancela o token atual, deixando o usuário sem token.
Observação: para consumir a API GraphQL é necessária a permissão “GQL000 – Consumir API GraphQL”. Para saber mais, clique aqui.
Como utilizar a API GraphQL na plataforma Banana Cake Pop?
Para configurar e explorar as consultas à API GraphQL pode ser utilizada a ferramenta “Banana Cake Pop”, que permite a execução fácil de consultas e mutações do GraphQL, com exploração visual dos esquemas. Veja a seguir as configurações necessárias:
1) Acesse a URL https://api.maxiprod.com.br/graphql/ui/ para acessar a ferramenta “Banana Cake Pop”:
2) Na tela inicial da ferramenta, clique em “Criar documento” ou “Navegar no esquema”.
3) A janela de configuração da conexão exibe alguns campos cujo preenchimento é inicializado automaticamente. Por exemplo, “Ponto final do esquema”, “Ponto final da assinatura”, “Ponto final de assinatura SSE”, “Protocolo de assinatura”, entre outros.
4) Clique na aba “Autorização” e, no campo “Type”, escolha “Bearer”. A seguir, preencha o campo “Token” com o token gerado anteriormente e preencha o campo “Prefix” com “Basic”. Clique no botão azul “Aplicar” para iniciar a conexão.
5) Na guia aberta pode-se consultar as “Referências de esquema” ou “Schema references”. É nesta aba que será possível encontrar os modelos das collections dos endpoints e seus respectivos campos. Se os esquemas de referências não estiverem carregados, clique no botão “Reload Schema”.
6) A partir da aba “Operations” é possível criar as requests. Clique no botão azul “Run” para efetivar a consulta.
Como utilizar a API GraphQL no Postman?
Veja a seguir como utilizar a API GraphQL no Postman:
1) Abra uma nova guia para montar a request. Para isso, clique no ícone “+” na parte superior da tela.
2) O tipo de request inicializado por padrão é o HTTP, portanto, altere para o tipo “GraphQL”.
3) Em seguida, insira a URL “https://api.maxiprod.com.br/graphql/” na barra de pesquisa, conforme imagem abaixo.
4) Preencha os parâmetros da autorização pelo cabeçalho, para isso, clique na opção “Headers” abaixo da barra de pesquisa. Se necessário, clique em “Query” para expandir estas opções.
5) No campo chave (Key) insira “Authorization” e no campo valor (Value) insira o “Token” gerado através do cadastro do usuário (conforme explicado no tópico mais acima, clique aqui para relembrar). Antes do token é necessário informar “Basic + espaço” no campo.
6) Após informar o token, o ambiente já se encontra conectado a API GraphQL do ERP MAXIPROD. Portanto, clique na opção “Query” e, em seguida, clique em “Use GraphQL Introspection”. Se os parâmetros informados estiverem corretos e, o usuário do token tiver a permissão citada acima (clique aqui para relembrar), serão listados todos os endpoints e os seus respectivos atributos e funções.
7) No campo a direita será automaticamente escrita a Query conforme o usuário for selecionando os endpoitns, atributos e funções.
8) Após montar a Query, faça a sua execução clicando no botão azul “Query” da barra de pesquisa. Os resultados serão exibidos na seção “Responde” mais abaixo, e podem ser visualizados de forma estruturada ou em formato de tabela.
Como montar uma consulta à API GraphQL no Excel ou Power BI?
1) No Excel, acesse a aba “Dados”. Em seguida clique em “Obter dados > De outras fontes > Consulta em branco”.
2) No Power BI acesse “Obter dados” na aba “Página inicial”. Clique em “Consulta em branco”.
3) A opção de “Consulta em branco” abre o editor do Power Query, em seguida clique em “Editor avançado”.
- No Power Query aberto pelo Excel, clique em “Editor avançado” na guia “Página inicial”.
- No Power Query aberto pelo Power BI, clique em “Editor avançado” na guia “Página inicial”.
4) Ao ser aberta a janela de “Consulta”, copie e cole a query abaixo e faça as alterações necessárias, como token, endpoint e demais parâmetros da consulta, etc. No exemplo abaixo está sendo utilizado o token de um assinante de testes, portanto, altere o token conforme o token gerado para o seu usuário. Clique em “Saiba mais” logo abaixo para visualizar a query.
let
Endpoint = "itensDosPedidosDeVendas",
Token = "INFORME O SEU TOKEN AQUI",
Consulta = "{ itensDosPedidosDeVendas (take:500 skip:0){ totalCount items{ id pedidoDeVenda { numero emissaoData cliente { apelido } } numero estado item { codigo descricao grupo { grupoDescricao } } quantidade unidade { codigo } valorUnitario valorTotal}}}",
Source = Web.Contents(
"https://api.maxiprod.com.br/graphql/",
[
Headers=[
#"Method"="POST",
#"Content-Type"="application/json",
#"Authorization"="basic " & Token
],
Content = Text.ToBinary("{""query"": "" " & Consulta & " ""}")
]
),
#"JSON" = Json.Document(Source),
#"Converted to Table" = Record.ToTable(JSON),
#"Expanded Value" = Table.ExpandRecordColumn(#"Converted to Table", "Value", {Endpoint}, {"Value."&Endpoint}),
#"Value.itens Expandido" = Table.ExpandRecordColumn(#"Expanded Value", "Value.itensDosPedidosDeVendas", {"totalCount"}, {"Value.itensDosPedidosDeVendas.totalCount"}),
#"Removed Columns" = Table.RemoveColumns(#"Value.itens Expandido",{"Name"}),
#"Value itens totalCount" = #"Removed Columns"{0}[Value.itensDosPedidosDeVendas.totalCount],
numeroDePaginas = Number.RoundUp(#"Value itens totalCount" / 500),
indicesDasPaginas = { 0 .. (numeroDePaginas - 1) },
obterRegistrosDaPagina = (pagina) =>
let resultados = pagina * 500
in
resultados,
paginas = List.Transform(indicesDasPaginas, each obterRegistrosDaPagina(_)),
#"Converted to Table1" = Table.FromList(paginas, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
#"Renamed Columns" = Table.RenameColumns(#"Converted to Table1",{{"Column1", "take"}}),
#"Changed Type" = Table.TransformColumnTypes(#"Renamed Columns",{{"take", type text}}),
#"Added Custom" = Table.AddColumn(#"Changed Type", "Custom", each let
ConsultaPaginacao = "{ itensDosPedidosDeVendas (take:500 skip: "&[take]&"){ totalCount items{ id pedidoDeVenda { numero emissaoData cliente { apelido } } numero estado item { codigo descricao grupo { grupoDescricao } } quantidade unidade { codigo } valorUnitario valorTotal}}}",
Source = Web.Contents(
"https://api.maxiprod.com.br/graphql/",
[
Headers=[
#"Method"="POST",
#"Content-Type"="application/json",
#"Authorization"= "basic " & Token
],
Content=Text.ToBinary("{""query"": """& ConsultaPaginacao &"""}")
]
),
#"JSON" = Json.Document(Source)
in
#"JSON"),
#"Custom Expandido" = Table.ExpandRecordColumn(#"Added Custom", "Custom", {"data"}, {"Custom.data"}),
#"Custom.data Expandido" = Table.ExpandRecordColumn(#"Custom Expandido", "Custom.data", {"itensDosPedidosDeVendas"}, {"Custom.data.itensDosPedidosDeVendas"}),
#"Custom.data.itensDosPedidosDeVendas Expandido" = Table.ExpandRecordColumn(#"Custom.data Expandido", "Custom.data.itensDosPedidosDeVendas", {"items"}, {"Custom.data.itensDosPedidosDeVendas.items"}),
#"Custom.data.itensDosPedidosDeVendas.items Expandido" = Table.ExpandListColumn(#"Custom.data.itensDosPedidosDeVendas Expandido", "Custom.data.itensDosPedidosDeVendas.items"),
#"Custom.data.itensDosPedidosDeVendas.items Expandido1" = Table.ExpandRecordColumn(#"Custom.data.itensDosPedidosDeVendas.items Expandido", "Custom.data.itensDosPedidosDeVendas.items", {"id", "pedidoDeVenda", "numero", "estado", "item", "quantidade", "unidade", "valorUnitario", "valorTotal"}, {"Custom.data.itensDosPedidosDeVendas.items.id", "Custom.data.itensDosPedidosDeVendas.items.pedidoDeVenda", "Custom.data.itensDosPedidosDeVendas.items.numero", "Custom.data.itensDosPedidosDeVendas.items.estado", "Custom.data.itensDosPedidosDeVendas.items.item", "Custom.data.itensDosPedidosDeVendas.items.quantidade", "Custom.data.itensDosPedidosDeVendas.items.unidade", "Custom.data.itensDosPedidosDeVendas.items.valorUnitario", "Custom.data.itensDosPedidosDeVendas.items.valorTotal"})
in
#"Custom.data.itensDosPedidosDeVendas.items Expandido1"5) Após copiar e colar a query na consulta e fazer as devidas alterações, verifique se não foi encontrado nenhum erro de sintaxe. Se não há erro, clique em “Concluído”.
6) Em seguida, clique em “Editar credenciais” e, na janela que será aberta, se a URL estiver correta, clique no botão “Conectar”.
7) Se não houver nenhuma divergência nos parâmetros da consulta, e a paginação não estiver ultrapassado o limite, será retornado o resultado na tela. A partir do qual o usuário pode “Expandir” os dados e fazer o tratamento necessário com tabelas e/ou gráficos.
8) Os parâmetros da consulta podem ser configurados pelas etapas aplicadas do editor do Power Query, facilitando a manipulação dos dados. Como, por exemplo, o token.
Quais as limitações de paginação da API GraphQL
Na consulta a API GraphQL, quando o usuário não define o parâmetro “take” para o endpoint a ser consultado, por padrão o sistema retorna a quantidade de 10 linhas. No entanto, para realizar uma consulta com mais linhas, o usuário pode definir o parâmetro “take”.
1) A limitação na paginação das consultas à API GraphQL segue o chamado cálculo de complexidade, que determina o limite em cada caso.
a) No cálculo de complexidade, são considerados os seguintes valores:
- Valor base (sempre existirá): 10
- Propriedades simples: 1
- Propriedades de navegação: nível x 10 (1×10, 2×10, 3×10…)
- PageInfo e totalCount não são considerados no cálculo de complexidade.
b) O valor resultante do cálculo de complexidade é utilizado como divisor do valor de referência padrão: 500.000 (quinhentos mil), que neste caso é o dividendo, sendo o quociente o limite de complexidade na consulta.
- Seguindo o exemplo acima, o cálculo seria (500.000/42= 11.904,7619047619). Ou seja, a limitação da consulta seria o valor de 11.904,7619047619.
2) Se o usuário exceder o limite de complexidade, será retornada a seguinte mensagem “The maximum allowed operation complexity was exceeded.”.
Se precisar de mais informações, fale com o suporte.