> For the complete documentation index, see [llms.txt](https://help.hyperflow.global/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.hyperflow.global/docs/builder-hyperflow/gerenciamento-de-aplicativos/fluxos/integracao/requisicao-graphql.md).

# Requisição GraphQL

## 🔗 Requisição GraphQL

O módulo **Requisição GraphQL** permite chamar um sistema externo que usa o padrão GraphQL, enviando uma consulta (query) ou alteração (mutation) e recebendo a resposta diretamente no fluxo. É útil para integrar com sistemas que trabalham dessa forma, em vez do formato tradicional de chamada.

{% hint style="info" %}
Para fazer uma chamada tradicional, com métodos como GET, POST ou PUT, use o módulo **Requisição HTTP**.
{% endhint %}

<figure><img src="/files/xq4fT80edQQQBdRAfN4m" alt=""><figcaption><p>Imagem 1 - Visão geral do módulo Requisição GraphQL na área de trabalho do fluxo no Hyperflow Integrações.</p></figcaption></figure>

***

### 🧭 Como acessar

1. No menu lateral, clique em **Gerenciamento de aplicativos**.
2. Em seguida, clique em **Fluxos**.
3. Abra ou crie um fluxo e acesse a área de trabalho do fluxo.
4. No painel de módulos, localize a categoria **Integração** (identificada pela cor azul).
5. Arraste o módulo **Requisição GraphQL** para a área de trabalho do fluxo.

<figure><img src="/files/klGuNYxgCeXFafCmiKS4" alt=""><figcaption><p>Imagem 2 - Painel de módulos com a categoria Integração expandida e o módulo Requisição GraphQL visível.</p></figcaption></figure>

{% hint style="warning" %}
Evite usar diretamente no endereço de destino uma variável que vem de algo digitado pelo cliente na conversa, sem validação — isso pode fazer a requisição ser enviada para um endereço não previsto.
{% endhint %}

***

### 🔍 Conhecendo o módulo

Ao clicar duas vezes no módulo na área de trabalho do fluxo, um painel de configuração é aberto na lateral da tela.

<figure><img src="/files/09ycACICrjjGEF3ybDc5" alt=""><figcaption><p>Imagem 3 - Painel de configuração do módulo Requisição GraphQL aberto.</p></figcaption></figure>

***

#### 🔗 Host

No campo **Host**, informe o endereço do sistema GraphQL que será chamado (aceita variáveis do fluxo).

<figure><img src="/files/jGBDT3cwISGcPr8DHYSP" alt=""><figcaption><p>Imagem 4 - Campo Host preenchido.</p></figcaption></figure>

***

#### 📋 Cabeçalhos

Informações extras enviadas junto da requisição, em formato JSON — normalmente usado para autenticação (ex.: `{"Authorization": "Bearer {{env.token}}"}`).

<figure><img src="/files/dH62O32WLaNiRKNLLsF9" alt=""><figcaption><p>Imagem 5 - Campo Cabeçalhos preenchido com um exemplo.</p></figcaption></figure>

***

#### 📝 Schema

No campo **Schema**, escreva a consulta (query) ou alteração (mutation) GraphQL a ser executada.

{% hint style="info" %}
Apesar do nome do campo, não é necessário informar uma definição de schema aqui — é neste campo que fica o conteúdo real da chamada (a consulta ou alteração GraphQL).
{% endhint %}

<figure><img src="/files/TtqXdOxdfXjDVB70ZGZe" alt=""><figcaption><p>Imagem 6 - Campo Schema preenchido com uma consulta GraphQL de exemplo.</p></figcaption></figure>

***

#### 🧩 Variáveis

Valores usados na consulta ou alteração GraphQL, em formato JSON. Aceita variáveis do fluxo.

<figure><img src="/files/C536zoedvpSZBZAdN1c9" alt=""><figcaption><p>Imagem 7 - Campo Variáveis preenchido com um exemplo.</p></figcaption></figure>

***

#### 🔀 Saídas do módulo

O módulo tem duas saídas:

* **Sucesso** — a chamada obteve uma resposta HTTP de sucesso.
* **Erro** — a chamada falhou por completo (por exemplo, tempo limite esgotado, endereço incorreto ou falha de conexão).

{% hint style="danger" %}
**Atenção:** mesmo que o sistema GraphQL retorne um erro de negócio (por exemplo, uma consulta inválida ou um campo não encontrado), o módulo segue pela saída **Sucesso**, já que tecnicamente a chamada foi respondida. Sempre verifique se a resposta contém um campo indicando erro antes de considerar a operação bem-sucedida no restante do fluxo.
{% endhint %}

<figure><img src="/files/vB5SI72WgSdXQBFN6wRE" alt=""><figcaption><p>Imagem 8 - Módulo na área de trabalho do fluxo mostrando as saídas Sucesso e Erro.</p></figcaption></figure>

***

### 💡 Caso de uso

**Cenário:** uma empresa quer consultar o status de um pedido em um sistema próprio que usa o padrão GraphQL.

**Configuração:**

1. Adicione o módulo **Requisição GraphQL** ao fluxo.
2. No campo **Host**, informe o endereço do sistema.
3. Em **Cabeçalhos**, informe o token de autenticação, se necessário.
4. No campo **Schema**, escreva a consulta do status do pedido, usando o código informado pelo cliente como variável.
5. Conecte a saída **Sucesso** a um módulo que verifique se a resposta contém dados válidos antes de informar o cliente.

**Resultado:** o fluxo consulta automaticamente o status do pedido no sistema GraphQL da empresa.

***

### 📌 Dicas úteis

* Use o campo **Cabeçalhos** para enviar tokens de autenticação exigidos pelo sistema chamado.
* Sempre trate a possibilidade de erro de negócio na resposta, já que a saída **Sucesso** não garante que a consulta foi processada sem problemas.
* Evite usar valores digitados pelo cliente diretamente no endereço de destino sem alguma validação prévia.

***

### 📝 Resumo

* O módulo **Requisição GraphQL** chama um sistema que usa o padrão GraphQL, enviando e recebendo dados no fluxo.
* Os campos principais são **Host**, **Cabeçalhos**, **Schema** e **Variáveis**.
* A saída **Sucesso** é ativada sempre que a chamada é respondida, mesmo com erro de negócio no conteúdo da resposta — verifique isso manualmente no restante do fluxo.
* A saída **Erro** só ocorre em falhas de comunicação (tempo limite, conexão, endereço incorreto).