> 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/controle-de-fluxo/transformar-json.md).

# Transformar JSON

O módulo **Transformar JSON** aplica uma expressão de transformação (no formato JSONata) sobre os dados atuais do fluxo e entrega o resultado para o próximo módulo. É útil quando você precisa reorganizar, filtrar, combinar ou calcular informações a partir de dados já coletados no fluxo, antes de usá-los em uma etapa seguinte.

{% hint style="info" %}
Este módulo é diferente do módulo **JSON**: o módulo JSON monta uma **resposta HTTP** (com código de status, cabeçalhos e corpo), enquanto o **Transformar JSON** apenas reprocessa dados no meio do fluxo e passa o resultado adiante — sem responder nada externamente.
{% endhint %}

## 🧭 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 **Controle de fluxo**.
5. Arraste o módulo **Transformar JSON** para a área de trabalho do fluxo.

{% hint style="warning" %}
**Antes de usar este módulo:** é recomendado ter um conhecimento básico da linguagem **JSONata**, usada para escrever a expressão de transformação. Você pode consultar a documentação oficial em [docs.jsonata.org](https://docs.jsonata.org/overview) para aprender a sintaxe.
{% 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.

### 🧮 Expressão de transformação

No campo principal, escreva a expressão **JSONata** que define como os dados do fluxo devem ser transformados. Essa expressão pode ler qualquer variável disponível no fluxo (como dados recebidos, variáveis do usuário ou do fluxo) e combiná-las, filtrá-las ou recalculá-las da forma que você precisar.

### 🧪 Playground (testar a expressão)

Use o botão de ação do módulo para abrir o **Playground**, um espaço para testar sua expressão antes de salvar:

1. No campo **Body**, informe um JSON de exemplo, parecido com os dados reais que o módulo vai receber no fluxo.
2. No campo **Query**, escreva a expressão JSONata que deseja testar.
3. O campo **Result** mostra automaticamente o resultado calculado a partir do Body e da Query informados.

### 🔀 Saída do módulo

* **Sucesso** — a expressão foi calculada corretamente. O resultado da transformação é entregue como dado de entrada para o próximo módulo do fluxo.
* **Erro** — a expressão informada é inválida ou não pôde ser calculada com os dados disponíveis. O fluxo segue por essa saída com uma mensagem descrevendo o problema.

{% hint style="warning" %}
O resultado da transformação fica disponível apenas no módulo conectado logo em seguida. Se precisar usá-lo mais adiante no fluxo, salve o valor em uma **Variável de Fluxo** ou **Variável de Usuário** logo depois deste módulo.
{% endhint %}

## 💡 Caso de uso

**Cenário:** um fluxo recebe os dados de um formulário preenchido pelo cliente, mas precisa reorganizar essas informações antes de enviá-las para um sistema externo.

**Configuração:**

1. Após receber os dados do formulário, adicione o módulo **Transformar JSON**.
2. Use o Playground para testar uma expressão que extraia apenas os campos necessários (por exemplo, nome e telefone) e monte um novo formato de dados.
3. Cole a expressão testada no campo principal e salve o módulo.
4. Conecte a saída **Sucesso** ao módulo que envia os dados para o sistema externo (por exemplo, uma **Requisição HTTP**).

**Resultado:** os dados chegam ao sistema externo já no formato esperado, sem precisar de várias etapas manuais de organização no fluxo.

## 📌 Dicas úteis

* Sempre teste sua expressão no **Playground** antes de salvar, usando um exemplo de dados parecido com o real.
* Use o resultado logo no módulo seguinte, ou salve-o em uma variável se precisar dele mais adiante no fluxo.
* Consulte a [documentação oficial do JSONata](https://docs.jsonata.org/overview) para aprender a sintaxe da linguagem de transformação.
* Use a saída **Erro** para tratar casos em que os dados esperados não estejam disponíveis ou estejam em um formato inesperado.

## 📝 Resumo

* O módulo **Transformar JSON** aplica uma expressão JSONata sobre os dados do fluxo e entrega o resultado ao próximo módulo.
* É diferente do módulo **JSON**, que monta respostas HTTP.
* O **Playground** permite testar a expressão com um exemplo de dados antes de salvar.
* Possui saídas separadas de **Sucesso** e **Erro**, dependendo do resultado do cálculo da expressão.