Nó GraphQL

O nó GraphQL (graphql_request) envia uma query ou mutation para qualquer endpoint HTTP GraphQL. O motor de workflows monta o body padrão GraphQL ({ "query": "...", "variables": { ... } }) e faz POST como JSON — você não precisa embrulhar o payload manualmente.

Figura 1: Campos do nó GraphQL — endpoint, query/mutation e variáveis

O que ele faz

A cada execução, o motor:

1. Resolve variáveis na URL do endpoint, na string da query e no JSON de variáveis
2. Valida que o campo Query/Mutation não está vazio
3. Faz POST de { "query": "<your query>", "variables": { ... } } para o endpoint
4. Retorna o status HTTP, data da resposta (payload GraphQL) e headers da resposta

Guia de configuração

Passo 1 — Adicionar o nó

1. Abra Automações
2. No grupo de paleta APIs, arraste GraphQL para o canvas
3. Posicione-o após nós que preparem IDs, filtros ou tokens de autenticação

Passo 2 — Definir o endpoint GraphQL (obrigatório)

Informe a URL HTTP do servidor GraphQL:

Variáveis são suportadas na URL: https://{{variables.hasura_host}}/v1/graphql

Passo 3 — Escrever a query ou mutation (obrigatório)

Use o campo de código Query/Mutation. Exemplo de query de leitura:

query GetContact($phone: String!) {
  contacts(where: { phone: { _eq: $phone } }, limit: 1) {
    id
    name
    email
    tags
  }
}

Exemplo de mutation:

mutation CreateLead($name: String!, $phone: String!) {
  insert_contacts_one(object: { name: $name, phone: $phone }) {
    id
    name
    phone
  }
}

Você pode usar variáveis de workflow dentro do texto da query quando o schema remoto permitir valores inline — prefira variables (próximo passo) para dados fornecidos pelo usuário, evitando problemas de injeção.

Passo 4 — Passar variáveis (JSON)

Mapeie variáveis GraphQL para dados do workflow:

{
  "phone": "{{trigger.body.telefone}}",
  "name": "{{trigger.body.nome}}"
}

Para uma query que declara $phone: String!, o motor envia:

{
  "query": "query GetContact($phone: String!) { ... }",
  "variables": {
    "phone": "5511999999999",
    "name": "Maria"
  }
}

Deixe as variáveis como {} ou vazio quando a operação não tiver parâmetros.

Passo 5 — Adicionar headers de autenticação

Endpoints GraphQL quase sempre exigem auth em headers HTTP (não no documento GraphQL):

Hasura (admin secret):

{
  "Content-Type": "application/json",
  "x-hasura-admin-secret": "{{variables.hasura_admin_secret}}"
}

Hasura (JWT de usuário):

{
  "Content-Type": "application/json",
  "Authorization": "Bearer {{variables.user_jwt}}"
}

Shopify:

{
  "Content-Type": "application/json",
  "X-Shopify-Access-Token": "{{variables.shopify_token}}"
}

GitHub:

{
  "Content-Type": "application/json",
  "Authorization": "Bearer {{variables.github_pat}}"
}

Passo 6 — Testar e ler resultados

1. Execute Test ou o botão Play do nó com um payload de gatilho representativo
2. Inspecione output.data — este é o envelope de resposta GraphQL
3. Use caminhos como {{gql_1.data.data.contacts[0].name}} (ajuste o ID do nó)

Passo 7 — Ramificar por erros GraphQL

GraphQL frequentemente retorna HTTP 200 com um array errors no body. Adicione um nó Condição:

• Sucesso: {{gql_1.data.errors}} vazio ou indefinido e {{gql_1.data.data}} existente
• Falha: notifique a equipe ou envie mensagem WhatsApp de fallback

Campos de saída

O nó retorna o mesmo wrapper HTTP do nó HTTP:

Dentro de data, a especificação GraphQL usa:

Exemplo de resposta bem-sucedida armazenada na saída do nó:

{
  "status": 200,
  "data": {
    "data": {
      "contacts": [{ "id": "uuid", "name": "Maria" }]
    }
  },
  "headers": { "content-type": "application/json" }
}

Caminhos de variáveis (node ID gql_1):

{{gql_1.status}}
{{gql_1.data.data.contacts[0].id}}
{{gql_1.data.errors[0].message}}

A paleta lista data e errors como dicas de saída — referem-se ao payload GraphQL dentro de {{nodeId.data}}, não a chaves de nível superior.

Dicas e boas práticas

• Use variáveis GraphQL ($phone, $id) para valores dinâmicos — nunca concatene entrada do usuário na string da query
• Solicite apenas os campos necessários — respostas menores executam mais rápido e são mais fáceis de depurar
• Nomeie operações (query GetOrder { ... }) ao salvar várias queries em nós diferentes para clareza
• Trate erros parciais — algumas APIs retornam data e errors juntos; não assuma que HTTP 200 significa sucesso de negócio
• Persista tokens em variáveis de workflow ou Settings → API Keys, não no editor de query
• Teste primeiro no GraphiQL/Playground, depois cole a query validada no nó
• Hasura: use x-hasura-admin-secret apenas em workflows server-side confiáveis; prefira JWT para dados com escopo de usuário
• Shopify: inclua a versão correta da Admin API no caminho da URL
• Combine com o nó HTTP quando o provedor expõe REST e GraphQL — escolha a API que corresponde à sua operação

FAQ

Recebo "Query/Mutation is required and cannot be empty"

O campo de query resolveu em branco após substituição de variáveis ou foi deixado vazio. Abra input_resolved no log de execução e confirme o texto da query.

HTTP 200 mas minha Condição trata como falha

Verifique {{nodeId.data.errors}}. GraphQL retorna erros no body enquanto o status HTTP permanece 200. Ramifique pelo array errors, não apenas por status.

Qual a diferença em relação ao nó HTTP?

O nó GraphQL monta automaticamente { query, variables } a partir de campos dedicados. Com o nó HTTP você definiria o mesmo JSON manualmente no campo body. Use GraphQL para clareza e validação do campo de query obrigatório.

Posso enviar requisições GET para GraphQL?

Alguns servidores suportam GET com ?query=; este nó sempre usa POST, que é o transporte recomendado para mutations e queries grandes.

Posso executar subscriptions (WebSocket)?

Não. Este nó suporta apenas requisição/resposta HTTP. Use o padrão webhook + HTTP/mutation para fluxos orientados a eventos.

Erro de parse no JSON de variáveis

Garanta JSON válido — aspas duplas nas chaves, sem vírgulas finais. Teste com {} estático primeiro e adicione referências {{...}} uma de cada vez.

Permissões negadas no Hasura

A role embutida no JWT (ou role padrão) pode não ter permissão para a operação. Verifique as permissões de metadata do Hasura ou use o admin secret / header de role correto.

Exemplos de casos de uso

Exemplo 1 — Buscar cliente no Hasura antes de enviar WhatsApp

Query:

query ByPhone($phone: String!) {
  contacts(where: { phone: { _eq: $phone } }, limit: 1) {
    id
    name
    opt_in_marketing
  }
}

Variables:

{ "phone": "{{trigger.body.telefone}}" }

Condição: se {{gql_1.data.data.contacts[0].opt_in_marketing}} for true → envie mensagem de campanha.

Exemplo 2 — Shopify — buscar pedido por nome

Endpoint: https://{{variables.shop_domain}}/admin/api/2024-01/graphql.json

Query:

query ($query: String!) {
  orders(first: 1, query: $query) {
    edges {
      node {
        id
        name
        displayFinancialStatus
        customer { displayName phone }
      }
    }
  }
}

Variables: { "query": "name:{{trigger.body.order_name}}" }

Send message: status do pedido a partir de {{gql_1.data.data.orders.edges[0].node.displayFinancialStatus}}.

Exemplo 3 — Mutation para registrar evento de CRM em API GraphQL externa

mutation LogEvent($input: EventInput!) {
  createEvent(input: $input) {
    event { id createdAt }
  }
}

{
  "input": {
    "type": "whatsapp_inbound",
    "phone": "{{trigger.body.telefone}}",
    "payload": {{trigger.body}}
  }
}

Ao embutir objetos JSON dentro de variáveis, valide primeiro em um nó JavaScript se o formato do payload for complexo.

Exemplo 4 — Query Hasura paginada com Loop

1. Variável offset = 0
2. GraphQL query com limit: 50, offset: $offset
3. JavaScript processa o lote e incrementa o offset
4. Condição continua enquanto o tamanho do lote for igual a 50

Referências de API e documentação relacionada