Eventos
Gateway Fluid

12min
Esta é a documentação da última versão (versão 2 - v2) do Fluid API Gateway.
Esta versão do Gateway funciona com a nova sintaxe da Fluid (v3) onde é possível recuperar os headers e query params do evento disparado para o Gateway.
Para a documentação da versão legada v1, acesse Gateway Fluid - v1﻿.
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 três informações essenciais:
gateway_host: O endereço do gateway varia de acordo com os Workspaces definidos para cada cliente. Consulte o gateway_host com a equipe responsável do projeto ou via Abertura de Chamados﻿.
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﻿.
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﻿.
Certifique-se de ter essas informações em mãos antes de criar um evento/webhook no Gateway Fluid. O gateway_host, flow_name e api_key são necessários para configurar corretamente o disparo do evento no ambiente Fluid.
Os métodos/verbos suportados para o disparo no gateway são:
GET
POST
PUT
PATCH
DELETE
HEAD
OPTIONS
O gateway_host é um endereço de acordo com os Workspaces﻿ definidos para cada cliente. Consulte o o seu gateway_host com a nossa equipe.
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"
}'
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"
}'
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.
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.
O corpo da resposta de um disparo síncrono será 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"
}'
curl --location '{gateway_host}/v2/flows/{flow_name}?sync=true&key={api_key}' \
--header 'Content-Type: application/json' \
--data '{
    "teste":"body"
}'
﻿
Se o disparo síncrono for feito com o método/verbo GET, não é necessário passar o parâmetro sync=truena URL.
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.
Definindo o response de um fluxo síncrono
Para retornar um response em um evento síncrono, 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&return_step={step_name}&key={api_key}' \
--header 'Content-Type: application/json' \
--data '{
    "teste":"body"
}'
curl --location '{gateway_host}/v2/flows/{flow_name}?sync=true&return_step={step_name}&key={api_key}' \
--header 'Content-Type: application/json' \
--data '{
    "teste":"body"
}'
﻿
@Deprecated return_array Na versão anterior v1 do Fluid Gateway, caso o retorno do passo fosse um array de objetos, era necessário adicionar um parâmetro chamado return_array com valor true, nesta última versão (v2) já não é mais necessário, o Gateway identifica automaticamente o tipo de response.
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"
}'
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﻿ no disparo de fluxos via Eventos﻿ 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"}'
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.
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.
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.
Updated 08 Oct 2024
Did this page help you?
Eventos
Gateway Fluid - v1