---
title: Gateway Fluid
slug: gateway-fluid
docTags: 
createdAt: 2023-11-17T14:40:27.462Z
---

Para disparar um evento/*webhook* para Fluid para iniciar a execução de um fluxo, é necessário fazê-lo via Gateway.

## Disparando fluxos via eventos/*webhooks*

Para disparar um evento/webhook e iniciar a execução de um fluxo utilizando o Gateway Fluid, é necessário ter acesso a duas informações essenciais:

- `flow_name`**:** Este é o nome do fluxo criado no console da plataforma. É usado para identificar qual fluxo será acionado pelo evento/webhook. Veja mais em [Canvas](docId:1q9GPDJoZXjsKAaG7_b2P).

:::hint{type="info"}
`api_key`: A chave de API gerada na plataforma Fluid. Essa chave é essencial para autenticar e autorizar o acesso ao Gateway Fluid. Saiba mais em [API Keys](docId\:U9RzUlsUP_oXxCqF5Mu_8).
:::

Certifique-se de ter essas informações em mãos antes de criar um evento/*webhook* no Gateway Fluid.

:::hint{type="info"}
Acesse [URL de disparo do fluxo](docId\:Qc2bDOEyA5nGZVsO0vlxB) para saber como obter a URL de disparo por *webhook*.
:::

:::hint{type="info"}
Os métodos/verbos suportados para o disparo no gateway são:

- `GET`
- `POST`
- `PUT`
- `PATCH`
- `DELETE`
- `HEAD`
- `OPTIONS`
:::

### Controle de idempotência

:::hint{type="info"}
Para saber mais sobre como a idempotência dos disparos é tratado, acesse [Controle de Idempotência](docId\:wE6VD6-EXCFVKUB_ZuBZ7) .
:::

**Limites Técnicos**

:::hint{type="warning"}
O tamanho máximo permitido para requisições ao nosso Gateway é de **10MB**. Certifique-se de que os payloads enviados estejam dentro desse limite para evitar erros.
:::

:::hint{type="warning"}
Eventos/*webhooks* **síncronos **devem ser usados com fluxos com tempo de resposta de até 29 segundos. Caso o fluxo leve 29 segundos ou mais para finalizar, use o disparo **assíncrono**.
:::

## Disparando um evento Assíncrono

O evento **assíncrono** retorna imediatamente um *HTTP status code* `200` e um `EventID`, permitindo que o fluxo seja executado em segundo plano. Este método é adequado quando não é necessário obter uma resposta imediata e quando o fluxo puder ser executado de forma **assíncrona**.

```shell
curl --location '{gateway_host}/v2/flows/{flow_name}?key={api_key}' \
--header 'Content-Type: application/json' \
--data '{
    "teste":"body"
}'
```

### Definindo a execução sequencial (serial)

Caso a execução de um fluxo não possa ser paralelizada, seja por restrição de *rate limit* de alguma API ou por requisitos de consistência de dados, é possível disparar o fluxo informando um parâmetro para execução serial.

```shell
curl --location '{gateway_host}/v2/flows/{flow_name}?key={api_key}&serial=true' \
--header 'Content-Type: application/json' \
--data '{
    "teste":"body"
}'
```

Com o parâmetro de *query* `serial=true` habilitado, o fluxo será executado um atrás do outro, sem concorrência.

:::hint{type="info"}
A configuração para execução de fluxos sequencialmente, um por vez, incorre numa configuração prévia por parte da equipe da Fluid e pode acarretar no aumento de consumo de créditos.
:::

## Disparando um evento Síncrono

Um evento/*webhook* para disparar um fluxo de forma **síncrona** mantém a requisição aberta até obter a resposta após a execução do fluxo. É útil quando a resposta do fluxo é necessária imediatamente quando do disparo do evento. Para tornar o evento **síncrono**, inclua o parâmetro de *query* `sync=true`.

:::hint{type="info"}
A partir da release [v3.23.2](docId\:Tdz42y8ajlhRthcdO9F_G) , o corpo e o status code da resposta agora refletem o **resultado real** do fluxo executado, conforme as regras abaixo:

- **Caso return\_step não seja informado** → retorna o *response* e *status code* do **último passo executado**
- **Com return\_step**, mas ocorre erro em algum passo antes dele → retorna o *response* e *status code* **de erro do último passo executado**
- **Com return\_step** executado com sucesso → retorna o *response* e *status code* do passo informado no **return\_step**
:::

Anteriormente a esta release, o corpo da resposta de um disparo síncrono seria **vazio**, a menos que informado o parâmetro `return_step` contendo o nome do passo que irá retornar a resposta (ver abaixo em "*Definindo o response de um fluxo síncrono*").

```shell
curl --location '{gateway_host}/v2/flows/{flow_name}?sync=true&key={api_key}' \
--header 'Content-Type: application/json' \
--data '{
    "teste":"body"
}'
```

:::hint{type="info"}
Se o disparo **síncrono** for feito com o método/verbo `GET`, não é necessário passar o parâmetro `sync=true`na URL.
:::

:::hint{type="warning"}
Eventos/*webhooks* **síncronos **devem ser usados com fluxos com tempo de resposta de até 29 segundos. Caso o fluxo leve 29 segundos ou mais para finalizar, use o disparo **assíncrono**.
:::

### Redefinindo o *response* de um fluxo síncrono

Para retornar um response e status code de um passo que não seja o último a ser executado em um fluxo durante a chamada síncrona, informe o **nome do passo** (`step_name`) do fluxo que gerará o retorno usando o parâmetro de query `return_step`.

```shell
curl --location '{gateway_host}/v2/flows/{flow_name}?sync=true&key={api_key}' \
--header 'Content-Type: application/json' \
--data '{
    "teste":"body"
}'
```

### Definindo o *Header* `Content-Type` do *response*

Por padrão, o *Content-Type* do *response* em eventos síncronos é `application/json`. Para definir outro valor para este *header*, passe o parâmetro `hct` na *query* via URL:

```shell
curl --location '{gateway_host}/v2/flows/{flow_name}?sync=true&hct=application/vnd.vtex.checkout.minicart.v1%2bjson&key={api_key}' \
--header 'Content-Type: application/json' \
--data '{
    "teste":"body"
}'
```

## Atribuindo Tags no disparo de eventos

Para atribuir [Tags](docId\:TTiU_EMXMPmfJBSviJA1_) no disparo de fluxos via [Eventos](docId\:UmtR8dLi6rNL8Us2V8O1A) basta informá-las como parâmetros de query (*query params*) com o nome `tags` e as valores separados por vírgula, da seguinte forma `&tags=tag1,tag2`:

```shell
curl --location '{gateway_host}/v2/flows/{flow_name}?key={api_key}&tags=tag1,tag2' \
--header 'Content-Type: application/json' --data '{"teste":"body"}'
```

É possível atribuir tags tanto na execução **síncrona** quanto **assíncrona** de fluxos.

:::hint{type="info"}
As tags utilizadas no disparo de fluxos devem seguir as seguintes regras: 

- São permitidas até **3 tags** por fluxo. 
- Cada tag pode ter no máximo **36 caracteres**.
- Devem ser compostas apenas por letras minúsculas, números e hífen.
- As tags são normalizadas, os espaços e acentos são removidos.

Caso as regras acima não sejam respeitadas, o gateway retornará um erro com *status code* `400`.
:::

## Demais configurações

### Disparando um fluxo no modo rascunho (versão não publicada)

Quando for necessário disparar um fluxo para testar uma alteração que ainda não foi publicada, isso é possível através do [Teste de fluxo](docId\:PvupLtH_USWaxj9j6uUkR) no canvas ou via Gateway através do parâmetro de query `draft=true`, como no exemplo abaixo:

```shell
curl --location '{gateway_host}/v2/flows/{flow_name}?key={api_key}&draft=true'
```

### Pré-processando o corpo da requisição

Caso seja necessário o tratamento do *body* enviado para o gateway removendo um prefixo, existe a configuração `trim_prefix` disponível via *query parameter* no disparo:

```shell
curl --location '{gateway_host}/v2/flows/{flow_name}?key={api_key}&trim_prefix=data%3D' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data 'data={"retorno":{"estoques":[{"estoque":{"id":123,"codigo":"","nome":"Nome do produto","estoqueAtual":1,"depositos":[{"deposito":{"desconsiderar":"N","id":"123","nome":"Geral","saldo":21,"saldoVirtual":21}}]}}]}}'
```

:::hint{type="info"}
Esse é um recurso importante na integração com o ERP [Bling](docId\:RLa13f-jTY-896sv2kzRK) para tratar o corpo do *callback* disparado pelo ERP. Com esse tratamento, o fluxo configurado na Fluid passará a contar exclusivamente com o JSON enviado pela Bling, sem a necessidade de fazer o tratamento do *body* no fluxo.
:::

### Obtendo o IP de origem do disparo

O header `X-forwarded-from` contendo o IP de origem do disparo é encaminhado para o fluxo, podendo ser tratado se necessário (como numa validação de whitelist).

::Image[]{src="https://api.archbee.com/api/optimize/G1NTw6yAi4RDUYbsU8csp/PYs1nmrIGkQXEIU8HZSk8_image.png" size="80" width="756" height="369" darkWidth="756" darkHeight="369" position="center" showCaption="false"}

## Conclusão

A utilização correta do Gateway Fluid (v2) é essencial para a execução eficaz de fluxos de processamento de forma **síncrona** ou **assíncrona**. Ao seguir esta documentação, você poderá disparar eventos de forma adequada e configurar fluxos para responder de acordo com suas necessidades. Certifique-se de consultar o `gateway_host` correto com a equipe responsável e ajustar os parâmetros conforme necessário para integrações bem-sucedidas utilizando esta versão do Fluid API Gateway.