Esta página mostra como utilizar a ferramenta API GraphQL para fazer consultas aos dados da sua empresa no ERP MAXIPROD. Ela permite fazer requisições ao banco de dados, agilizando a troca de informações do ERP MAXIPROD com outros sistemas.
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.
Lembre-se: a API GraphQL permite a consulta de dados, não sua atualização.
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.
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: especifique os dados necessários 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: a tipagem forte permite uma melhor compreensão e validação dos dados, garantindo 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 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 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. 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”, 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, é necessário fazer logoff e novo login, para que a nova permissão passe a funcionar.
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 menu superior “Roda dentada > Gerar token de acesso à API GraphQL”.
2) A tela de 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 a seguir 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 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.
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 encontram-se 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) Na aba “Operations” pode-se 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 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 visualizados 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 não 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.