Esta página mostra como utilizar a API GraphQL para fazer consultas aos dados da sua empresa no ERP MAXIPROD, agilizando a troca de informações com outros sistemas. A API GraphQL permite a consulta de dados, não sua atualização.
Com a API GraphQL, pode-se:
a) construir relatórios personalizados com ferramentas como Power BI e Excel.
b) enviar informações do ERP MAXIPROD para sistemas de terceiros.
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 Nitro (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.
GraphQL é uma linguagem de consulta e um ambiente de execução criado pelo Facebook, para simplificar a interação com APIs de forma mais eficiente do que os métodos tradicionais, como REST. Permite solicitar exatamente os dados necessários, sem excesso de informações ou solicitações adicionais.
Benefícios da API GraphQL:
- Flexibilidade: os dados são buscados em uma única consulta, eliminando a necessidade de múltiplas chamadas à API.
- Eficiência: reduz o tráfego de rede e melhore o desempenho da aplicação, transmitindo apenas os dados necessários.
- Tipagem forte: a tipagem forte permite uma melhor compreensão e validação dos dados, melhorando a integridade e consistência.
- Documentação clara: uma documentação detalhada facilita o uso da API e detalha 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 saber mais sobre perfis e permissões de acesso, clique aqui.
Importante: Atualmente, em assinantes “Multi-CNPJ” o usuário deve ter esta permissão em todas as empresas (CNPJs) cadastradas, para que possa utilizar a API GraphQL.
Esta permissão, como todas as demais, só podem ser atribuídas por usuários ADMIN.
Para adicionar esta permissão:
1) 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 são 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.
c) Na tela seguinte, selecione a permissão a incluir e clique no botão “Ok”, no canto inferior direito. 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, é necessário fazer logoff e novo login, para que a nova permissão passe a funcionar.
Como gerar o token de acesso à API GraphQL?
Para gerar o token de acesso, é necessária a permissão “USU009 – Gerenciar tokens de acesso à APIs” na empresa logada. Para saber mais sobre perfis e permissões de acesso, clique aqui.
1) Acesse o menu superior “Roda dentada > Gerar token de acesso à API GraphQL”.
2) Abre-se a grade de usuários.
3) Clique nos três pontinhos na coluna “Ações” e a seguir na opção “Token de acesso API GraphQL” (na nova grade de usuários, algumas funcionalidades ainda não foram implementadas, como, por exemplo, a edição/exclusão de um usuário, mas já é possível gerar o token de acesso).
4) Na janela aberta, se o usuário ainda não tem token de acesso, o sistema exibe a mensagem “O usuário não possui um token de acesso.” e, logo abaixo, o botão verde “Gerar”. Clique neste botão para gerar o token pela primeira vez.
5) É mostrado o token de acesso. Clique no botão “Copiar” para copiá-lo para a área de transferência.
6) Quando o token é criado, são exibidos na janela os botões “Recriar” e “Revogar”. “Recriar” cria um novo token, sobrescrevendo o anterior, e “Revogar” cancela o token atual, deixando o usuário sem token.
Como utilizar a API GraphQL na plataforma Nitro (Banana Cake Pop)?
Para configurar e explorar as consultas à API GraphQL pode ser utilizada a ferramenta “Nitro (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 “Nitro (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 os esquemas, clicando em “Schema references”. Nesta aba encontram-se os modelos das collections dos endpoints e seus respectivos campos. Se os esquemas não estiverem carregados, clique no botão “Reload Schema”.
6) Na aba de Operações (“Operations”) pode-se criar as requisições (“requests”). Clique no botão azul “Run” para efetivar a consulta.
Como utilizar a API GraphQL no Postman?
No Postman, a montagem das consultas é um pouco mais fácil do que no Nitro.
1) Abra uma nova guia para montar a requisição. Para isso, clique no ícone “+” na parte superior da tela.
2) O tipo de requisição inicializado por padrão é o HTTP, portanto altere para o tipo “GraphQL”.
3) A seguir, insira a URL “https://api.maxiprod.com.br/graphql/” na barra de pesquisa, conforme a 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á estará conectado à API GraphQL do ERP MAXIPROD. Portanto, clique na opção “Query” e, a seguir, 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 à direita será automaticamente escrita a Query conforme o usuário for selecionando os endpoints, atributos e funções.
8) Após montar a Query, execute-a clicando no botão azul “Query” da barra de pesquisa. Os resultados serão exibidos na seção “Responde” mais abaixo, e podem ser exibidos de forma estruturada ou em formato de tabela.
Como montar uma consulta à API GraphQL em Excel ou Power BI?
1) No Excel, acesse a aba “Dados”. A seguir, 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, a seguir 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. No exemplo abaixo é utilizado o token de um assinante de teste, portanto altere o token conforme o token gerado para o seu usuário. Clique em “Detalhes (Details)”, 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 foi encontrado algum erro de sintaxe. Se não há erro, clique em “Concluído”.
6) Clique em “Editar credenciais” e, na janela aberta, se a URL estiver correta, clique no botão “Conectar”.
7) Se os parâmetros da consulta estão corretos, e a paginação não ultrapassa o limite, é 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 através 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 à API GraphQL, se o usuário não define o parâmetro “take” para o endpoint a consultar, por padrão o sistema retorna 10 linhas. Para 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 é usado como divisor do valor de referência padrão 500.000 (que neste caso é o dividendo), sendo o quociente o limite de complexidade na consulta.
- Seguindo no exemplo acima, o cálculo seria (500.000/42= 11.904,7619047619). Ou seja, o limite de complexidade da consulta seria 11.904,7619047619.
2) Se o usuário exceder o limite de complexidade, é retornada a mensagem “The maximum allowed operation complexity was exceeded.”.
Importante: a limitação máxima para o “take” é 1.000.000 (um milhão) de registros.
Para mais informações, fale com o suporte.