Gateway Fluid

18 min

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.

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.

Acesse URL de disparo do fluxo para saber como obter a URL de disparo por webhook.

Os métodos/verbos suportados para o disparo no gateway são:

POST

PATCH

DELETE

HEAD

OPTIONS

Controle de idempotência

Para saber mais sobre como a idempotência dos disparos é tratado, acesse Controle de Idempotência .

Limites Técnicos

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.

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.

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.

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.

A partir da release v3.23.2 , 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").

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.

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.

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:

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:

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.

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 no canvas ou via Gateway através do parâmetro de query draft=true, como no exemplo abaixo:

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:

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}}]}}]}}'

Esse é um recurso importante na integração com o ERP Bling 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).

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.