Requisição GraphQL

O módulo Requisição GraphQL permite chamar uma API 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 externos que expõem esse tipo de API, em vez de uma API REST tradicional.

Para chamar uma API REST tradicional (com métodos GET, POST, PUT, etc.), use o módulo Requisição REST.

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.

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.

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.

Host

No campo Host, informe o endereço da API GraphQL que será chamada (aceita variáveis do fluxo).

Cabeçalhos

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

Query/Mutation GraphQL

Escreva a consulta (query) ou alteração (mutation) GraphQL a ser executada.

Variáveis

Valores usados pela query ou mutation, em formato JSON. Aceita variáveis do fluxo.

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).

Atenção: mesmo que a API 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.

Caso de uso

Cenário: uma empresa quer consultar o status de um pedido em um sistema próprio que expõe uma API GraphQL.

Configuração:

1. Adicione o módulo Requisição GraphQL ao fluxo.

2. No campo Host, informe o endereço da API.

3. Em Cabeçalhos, informe o token de autenticação, se necessário.

4. Na Query/Mutation GraphQL, 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 na API GraphQL da empresa.

Dicas úteis

• Use o campo Cabeçalhos para enviar tokens de autenticação exigidos pela API.

• 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 uma API GraphQL, enviando e recebendo dados no fluxo.

• Os campos principais são Host, Cabeçalhos, Query/Mutation GraphQL 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).