O que significa acesso a queries por API GraphQL?

O GraphQL é uma linguagem de consulta poderosa que permite buscar dados de forma flexível e eficiente, direto do seu sistema Keepfy. Com esse recurso, você pode criar consultas personalizadas para extrair dados específicos de consultas que o sistema já utiliza, como ordens de serviço, e utilizá-las em ferramentas externas.

Imagine gerar dashboards dinâmicos ou relatórios customizados em outros sistemas que permitem esse tipo de consulta, como é o caso do Microsoft Power Bi. Isso significa mais controle e autonomia para transformar os dados do Keepfy em insights valiosos para o seu negócio.

Qual o objetivo deste artigo?

Nosso objetivo aqui é apresentar uma pequena introdução das possibilidades da API GraphQL do Keepfy e como ela pode agregar valor ao seu dia a dia. No entanto, vale destacar que, para trabalhar com essa API, é necessário um certo nível de conhecimento em programação e familiaridade com a lógica do GraphQL. Este artigo serve como ponto de partida, mas pressupomos que o cliente ou desenvolvedor que for utilizá-la já tenha noções básicas de como construir consultas e integrar APIs em suas ferramentas.

É importante destacar que não oferecemos suporte para construção ou manutenção dos modelos específicos que foram construídos, mas podemos oferecer parceiros que o fazem.

Por onde começar?

O caminho ideal é começar consultando a nossa documentação oficial aqui. Lá você encontra detalhes sobre as queries disponíveis e exemplos para começar a usar.

Por quê não vejo a seção Integrações Externas em Minha Conta?

Se você não está vendo a opção de Integrações Externas no Keepfy, é porque esse acesso precisa ser liberado internamente para sua organização. Para ativar, entre em contato conosco pelo chat de atendimento e faça a requisição. Nosso time de produto vai liberar este recurso para você.

Como eu posso utilizar?

A API GraphQL do Keepfy abre portas para diversas possibilidades, e uma das formas mais práticas de gerar valor é integrá-la ao Microsoft Power BI para buscar dados e criar relatórios personalizados. Abaixo, mostramos os passos principais para começar com um exemplo de busca por dados de ordens de serviço.

Importante: Embora apresentemos os exemplos de consulta abaixo e de poder auxiliar no entendimento de algumas consultas, não oferecemos suporte direto ao Microsoft Power BI nem podemos auxiliar na construção dos seus modelos nesta ferramenta — os exemplos abaixo são apenas um ponto de partida.

Como gerar o token de acesso via função no Microsoft Power Bi?

Após gerar seu accessKey e accessSecret pelo Keepfy é possível a partir da funcionalidade 'Criar consulta em branco' no editor avançado do Power Query criar uma função que irá auxiliar na geração do token de acesso para futuras consultas na busca pelos dados.

Esse é um exemplo que irá retornar o token a partir da execução da mutation denominada createAccessToken:

() =>
let
    url = "https://app.keepfy.com/graphql",
    body = "{""query"": ""mutation{createAccessToken(fields:{accessKey:\""insira_aqui_seu_accessKey\"",accessSecret:\""insira_aqui_seu_accessSecret\""}){token}}""}",
    Source = Web.Contents(url, [
        Headers = [#"Content-Type" = "application/json"],
        Content = Text.ToBinary(body)
    ]),
    JsonResponse = Json.Document(Source),
    Token = JsonResponse[data][createAccessToken][token]
in
    Token

Como criar uma consulta para obter dados de ordens de serviço via função no Microsoft Power Bi?

Agora que possuímos a função para gerar o token, podemos explorar a criação de uma função que irá realizar a busca de dados de ordens de serviço baseadas no contexto de acesso disponibilizado pelo accessToken.

Neste exemplo, estamos buscando por ordens de serviço abertas e canceladas especificando a busca para trazer apenas algumas colunas dessa entidade, determinada pelo "items" da query ServiceOrders.

É importante notar também que essa query requer um trabalho de paginação pois espera-se um grande volume de dados, portanto, a função está preparada para iterar até que todas as ordens sejam carregadas ao modelo.

(skip as number) =>
let
    token = GetAccessToken(),
    url = "https://app.keepfy.com/graphql",
    body = "{
        ""query"": ""query ServiceOrders($pagination: Pagination, $query: ServiceOrderQueryInput!) { serviceOrders(pagination: $pagination, query: $query) { items { id code branchId service situation stoppedAt resumedAt } hasMore } }"",
        ""variables"": {
            ""pagination"": {
                ""skip"": " & Text.From(skip) & ",
                ""limit"": 100
            },
            ""query"": { ""filter"": { ""situations"": [""Opened"", ""Closed""] }}
        }
    }",
    Source = Web.Contents(url, [
        Headers = [#"access-token" = token, #"Content-Type" = "application/json"],
        Content = Text.ToBinary(body),
        ManualStatusHandling = {400, 401, 403, 404}
    ]),
    JsonData = Json.Document(Source),
    Data = JsonData[data],
    ServiceOrders = Data[serviceOrders],
    Items = ServiceOrders[items],
    HasMore = ServiceOrders[hasMore]
in
    [Items = Items, HasMore = HasMore]

Se tudo der certo com a consulta, teremos ao final uma tabela carregada semelhante a está:

A partir de agora é possível utilizar as tabelas carregadas para gerar dashboards e indicadores personalizados.

Restrições de Uso

Para garantir a estabilidade do sistema e evitar sobrecarga, temos algumas recomendações e limites:

Frequência de consultas: Recomendamos que você configure suas buscas para rodar apenas uma vez por dia. Após construir seus modelos semânticos (como dashboards ou relatórios), planeje a execução diária para manter tudo funcionando sem problemas.
Bloqueio por excessos: Se identificarmos um volume excessivo de requisições diárias por meio deste canal, elas serão bloqueadas para proteger a performance do sistema. Planeje bem o uso para evitar interrupções.