Conceitos fundamentais

O Flowker é construído em torno de um conjunto de conceitos interconectados. Entender como eles se relacionam ajuda você a projetar, configurar e executar workflows com eficiência. A última seção desta página mostra como tudo se encaixa.

Workflows

Um workflow é a definição de um processo de negócio — a sequência de passos que o Flowker segue para concluir uma operação. Todo workflow possui um ciclo de vida com três estados possíveis:

Status	Descrição
`draft`	Criado e editável. Ainda não pode ser executado.
`active`	Pronto para execução. A estrutura está bloqueada.
`inactive`	Desativado. Novas execuções não são aceitas.

Para alterar o estado de um workflow, use os endpoints ativar, desativar e mover para draft.

Nodes e edges

Os nodes são os passos individuais de um workflow — o que em termos de negócio você chamaria de tarefas. Cada node é uma unidade de trabalho: receber um evento, chamar um serviço, avaliar uma condição ou executar uma ação. O Flowker suporta quatro tipos de node:

Tipo	Propósito	Quando usar
`trigger`	Ponto de entrada do workflow	Sempre o primeiro node. Inicia a execução quando um evento ocorre.
`executor`	Chama um serviço externo por uma configuração de provider	Quando você precisa chamar uma API ou integração externa.
`conditional`	Bifurca a execução com base em condições	Quando o próximo passo depende do resultado do anterior.
`action`	Executa uma ação integrada; o tipo disponível é `set_output`, que define o output final da execução	Para definir o output final do workflow sem uma chamada externa.

Os edges conectam nodes e definem a ordem de execução. A ramificação fica no node conditional, não no edge: o node conditional avalia sua condição e produz um handle de resultado, e o Flowker segue o único edge de saída cujo sourceHandle corresponde a esse handle. Todos os outros tipos de node seguem todos os seus edges de saída.

Catálogo

O catálogo é o registro somente leitura de todos os providers, executors e triggers integrados disponíveis no Flowker. Você não pode criar ou modificar entradas do catálogo — apenas descobri-las. Antes de configurar qualquer integração, explore o catálogo para ver o que está disponível:

Os executors do catálogo são os componentes integrados que um node invoca — o conector HTTP genérico e as operações de providers nativos como o ledger do Midaz e o Tracer. Você os descobre; você nunca os cria.
Os triggers definem os tipos de eventos que podem iniciar um workflow (ex: webhooks).

Use estes endpoints para explorar o que está disponível:

Listar executors do catálogo e Listar triggers do catálogo para descobrir tipos de executor e trigger.
Listar providers do catálogo (GET /v1/catalog/providers) para listar todos os providers disponíveis.
Consultar provider do catálogo (GET /v1/catalog/providers/{id}) para obter detalhes de um provider específico.
Listar executors por provider (GET /v1/catalog/providers/{id}/executors) para listar os executors disponíveis para um provider específico.

Configurações de provider

Uma configuração de provider é a sua conexão com uma instância ativa de um serviço externo. É o objeto para o qual um node aponta e o objeto que o Flowker lê quando esse node é executado. O Flowker separa o tipo de serviço da sua conexão com ele:

Conceito	O que é	Natureza
Provider	Um tipo de serviço externo (ex: Midaz, Tracer, um endpoint HTTP genérico).	Estático — publicado no catálogo.
Configuração de provider	Sua conexão com uma instância desse provider.	Dinâmica — você cria e gerencia.

Cada configuração de provider contém:

config — os detalhes de conexão daquela instância, como a URL base e as credenciais de autenticação. Para o kind padrão catalog, o Flowker valida esse mapa com o JSON Schema do provider do catálogo. Para external_openapi, usa um validador de configuração de OpenAPI externa. Os campos sensíveis reconhecidos são gravados no backend de segredos e substituídos por secretRef; configurações legadas sem secretRef podem conter valores em linha.
allowedHosts — os hosts públicos que esta configuração pode chamar.
allowedPrivateHosts — hosts privados nomeados que seu time de operações permite que esta configuração alcance. Ele suspende apenas a restrição do Flowker para endereços privados ou loopback: se allowedHosts não estiver vazio, também deverá incluir o host. Endereços de metadados de nuvem e link-local continuam bloqueados.
schemaBindings — os schemas XSD ou OpenAPI vinculados a esta configuração, cada um com uma restrição opcional a operações OpenAPI específicas.

Uma configuração carrega também um kind. Os valores compatíveis são catalog (o padrão), que conecta a um provider do catálogo, e external_openapi, que conecta a um documento OpenAPI que você mesmo subiu para que um node de workflow chame as operações da sua própria API — veja Conectando a sua própria API. As configurações de provider possuem dois status: active (em uso) e disabled (temporariamente offline). Use Desabilitar configuração de provider para tirar uma conexão de serviço e Habilitar configuração de provider para trazê-la de volta.

Como um workflow a alcança

Todo node executor pode carregar um providerConfigId — o identificador da configuração de provider pela qual ele chama. Em tempo de execução, o Flowker monta cada requisição de saída com a URL base dessa configuração de provider mais o path do node, e o node falha se a configuração de provider não estiver active. Use os endpoints de Configurações de provider para criar, ler, atualizar, desabilitar, habilitar e remover suas conexões.

Registro de configurações de executor

O Flowker mantém um registro de configurações de executor. O registro expõe quatro operações:

Operação	Endpoint
Listar	`GET /v1/executors`
Consultar	`GET /v1/executors/{id}`
Atualizar	`PATCH /v1/executors/{id}`
Remover	`DELETE /v1/executors/{id}`

Cada registro carrega um status, que a API informa em cada resposta:

Status	Descrição
`unconfigured`	O registro ainda não tem detalhes de conexão.
`configured`	O registro carrega detalhes de conexão.
`tested`	O registro foi verificado.
`active`	O registro está em serviço.
`disabled`	O registro está fora de serviço.

O corpo de atualização não inclui status, mas a operação de listagem o aceita como filtro de consulta. A atualização se aplica a registros em status unconfigured ou configured; a remoção se aplica a registros em status unconfigured, configured ou disabled. Nenhuma operação nesta versão move um registro para tested, active ou disabled; a tabela lista esses valores porque as respostas os informam e o filtro de listagem os aceita.

Templates

Templates de workflow são padrões pré-construídos publicados no catálogo. Cada template descreve um padrão de integração conhecido e os parâmetros que esse padrão espera. O catálogo traz o template tracer-midaz-validation (“Tracer Validation + Midaz Transaction”): ele recebe uma requisição de webhook, valida a transação no Tracer e cria a transação no Midaz quando o Tracer aprova. Cada template possui um schema de parâmetros que define quais entradas ele espera (ex: qual configuração de provider usar, valores de limiar). Quando o Flowker consegue recuperar configurações de provider ativas, ele enriquece os campos de parâmetros referenciados com opções selecionáveis. Se a consulta não estiver disponível ou falhar, ele retorna o schema original. Para inspecionar um template:

Liste os templates do catálogo.
Consulte o detalhe do template para ver seu schema de parâmetros.
Valide um conjunto de parâmetros contra esse schema.

Execuções

Uma execução é uma instância em tempo de execução de um workflow. Um disparo normalmente inicia uma nova execução; uma retentativa que reutiliza uma chave de idempotência existente retorna a execução preexistente em vez de criar outra. Cada execução registra:

executionId — Identificador único desta execução.
status — Estado atual: pending, running, completed ou failed.
stepResults — A saída de cada node executor, condicional ou de ação executado, em ordem. Nodes trigger iniciam a travessia do grafo e não criam registros de etapas de execução.
finalOutput — O valor final persistido para a execução. Quando uma ação set_output produz um objeto, o Flowker usa esse objeto; caso contrário, retorna o contexto acumulado do workflow.

Use Consultar status da execução para monitorar o progresso e Consultar resultados da execução para obter a saída completa.

O endpoint de status retorna o registro da execução, incluindo seu status atual. O endpoint dedicado de resultados (GET /v1/executions/{id}/results) retorna status, stepResults e finalOutput quando presente. Uma etapa com falha pode incluir errorMessage; esta resposta não tem um campo de detalhes de erro de nível superior.

Idempotência

Requisições diretas de execução requerem uma string Idempotency-Key não vazia; o Flowker não exige formato UUID. O header de webhook é opcional. Se o Flowker receber uma segunda requisição com o mesmo Idempotency-Key, ele retorna a execução preexistente em vez de criar outra. Uma repetição direta retorna HTTP 200 e inclui idempotencyReplayed na resposta.

Idempotency-Key: 7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b

Use uma nova chave quando quiser criar uma nova execução intencionalmente. Reutilize a mesma chave apenas ao reenviar exatamente a mesma requisição.

Dashboard

A API de Dashboard fornece resumos agregados dos seus workflows e execuções — útil para construir dashboards operacionais e ferramentas de monitoramento. Use-a sempre que precisar de uma visão de alto nível da saúde do sistema sem consultar execuções individuais.

Resumo de workflows retorna totais e detalhamentos por status (draft, active, inactive).
Resumo de execuções retorna totais e detalhamentos por status, com filtros opcionais de intervalo de tempo e status.

Exemplo de resposta de GET /v1/dashboards/executions:

{
  "total": 12847,
  "completed": 11903,
  "failed": 712,
  "pending": 130,
  "running": 102
}

Casos de uso comuns:

Monitorar a saúde das execuções — acompanhe as taxas de conclusão e falha ao longo do tempo para identificar degradações precocemente.
Construir páginas de status — exiba métricas de throughput e sucesso dos workflows em dashboards internos ou voltados ao cliente.
Alertar sobre picos de taxa de falha — compare failed / total com um limiar para disparar alertas antes que problemas se propaguem.

Como tudo se encaixa

Os conceitos do Flowker se constroem uns sobre os outros em uma sequência clara:

Explore o catálogo para descobrir providers, executors do catálogo, triggers e templates disponíveis.
Crie configurações de provider para conectar o Flowker a instâncias ativas de serviços externos.
Defina workflows — cada node executor nomeia um executor do catálogo e a configuração de provider pela qual ele chama.
Execute workflows para rodar seu processo de negócio e obter resultados.
Monitore — use o dashboard para resumos operacionais e a API de execuções para o detalhe por passo.

Pronto para ver isso na prática? Siga o guia de primeiros passos para executar seu primeiro workflow do início ao fim.

Visão geral

Guias

Console

Operações

Conceitos fundamentais

Workflows

Nodes e edges

Catálogo

Configurações de provider

Como um workflow a alcança

Registro de configurações de executor

Templates

Execuções

Idempotência

Dashboard

Como tudo se encaixa

​Workflows

​Nodes e edges

​Catálogo

​Configurações de provider

​Como um workflow a alcança

​Registro de configurações de executor

​Templates

​Execuções

​Idempotência

​Dashboard

​Como tudo se encaixa

Workflows

Nodes e edges

Catálogo

Configurações de provider

Como um workflow a alcança

Registro de configurações de executor

Templates

Execuções

Idempotência

Dashboard

Como tudo se encaixa