Conceitos centrais

O Flowker é construído sobre um conjunto de conceitos interligados. A última seção desta página mostra como tudo se conecta.

Workflows

Um workflow é a definição de um processo de negócio, a sequência de etapas que o Flowker segue para concluir uma operação. Os workflows passam por um ciclo de vida:

Status	Descrição
`draft`	Criado e editável. Ainda não pode rodar.
`active`	Pronto para executar. A estrutura está travada.
`inactive`	Desativado. Nenhuma nova execução é aceita.

Para mover um workflow entre estados, use os endpoints ativar, desativar e mover para rascunho.

Nós e arestas

Os nós são as etapas individuais de um workflow, ou tarefas em termos de negócio. Cada nó é uma unidade de trabalho: receber um evento, chamar um serviço, avaliar uma condição ou fazer uma ação. O Flowker tem quatro tipos de nó:

Tipo	Objetivo	Quando usar
`trigger`	Ponto de entrada do workflow	Sempre o primeiro nó. Começa a execução quando um evento acontece.
`executor`	Chama um serviço externo por uma configuração de provedor	Quando você precisa chamar uma API ou integração externa.
`conditional`	Ramifica a execução com base em condições	Quando a próxima etapa depende do resultado de uma anterior.
`action`	Faz uma ação embutida; o tipo disponível é `set_output`, que define a saída final da execução	Para definir a saída final do workflow sem uma chamada externa.

As arestas conectam os nós e definem a ordem de execução. A ramificação fica no nó condicional, não na aresta: o nó condicional avalia a condição dele e produz um handle de resultado, e o Flowker segue a única aresta de saída cujo sourceHandle corresponde a esse handle. Todos os outros tipos de nó seguem todas as arestas de saída deles.

Catálogo

O catálogo é o registro somente leitura de todos os provedores, executores e gatilhos embutidos disponíveis no Flowker. Você não pode criar nem alterar entradas do catálogo. Você as descobre. Antes de configurar qualquer integração, navegue pelo catálogo para ver o que já está disponível:

Os executores de catálogo são os componentes embutidos que um nó de workflow invoca. Eles incluem o conector HTTP genérico e as operações de provedores nativos como o ledger do Midaz e o Tracer.
Os gatilhos definem os tipos de evento que podem iniciar um workflow (por exemplo, webhooks).

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

Listar executores do catálogo e Listar gatilhos do catálogo para descobrir os tipos de executor e de gatilho.
Listar provedores do catálogo (GET /v1/catalog/providers) para listar todos os provedores disponíveis.
Obter provedor do catálogo (GET /v1/catalog/providers/{id}) para ver os detalhes de um provedor específico.
Listar executores por provedor (GET /v1/catalog/providers/{id}/executors) para listar os executores disponíveis em um provedor específico.

Configurações de provedor

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

Conceito	O que é	Natureza
Provedor	Um tipo de serviço externo (por exemplo, Midaz, Tracer, um endpoint HTTP genérico).	Estático — publicado no catálogo.
Configuração de provedor	A sua conexão com uma instância desse provedor.	Dinâmico — você as cria e gerencia.

Cada configuração de provedor guarda:

config: os dados de conexão daquela instância, como a URL base e as credenciais de autenticação. Para a espécie padrão catalog, o Flowker valida esse mapa contra o JSON Schema do provedor de catálogo. Para external_openapi, ele usa um validador de configuração de OpenAPI externo. As folhas sensíveis reconhecidas são gravadas no backend de segredos e substituídas por secretRef. Configurações antigas sem secretRef podem conter valores inline.
allowedHosts: os hosts públicos que esta configuração pode chamar.
allowedPrivateHosts: hosts privados nomeados que o seu time de operações permite que esta configuração alcance. Ele levanta apenas a restrição do Flowker a endereços privados ou de loopback: se allowedHosts não estiver vazia, ela também deve incluir o host. Metadados de cloud e endereços link-local seguem 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 também carrega um kind. Os valores aceitos são catalog (o padrão), que conecta a um provedor do catálogo, e external_openapi, que conecta a um documento OpenAPI que você mesmo subiu, para que um nó de workflow chame as operações da sua própria API. Veja Conectar a sua própria API. As configurações de provedor têm dois status: active (em uso) e disabled (temporariamente fora do ar). Use Desabilitar configuração de provedor para tirar uma conexão de serviço e Habilitar configuração de provedor para trazê-la de volta.

Como um workflow chega até ela

Cada nó de executor pode carregar um providerConfigId, o identificador da configuração de provedor 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 provedor mais o caminho definido no nó, e o nó falha se a configuração de provedor não estiver active. Use os endpoints de Configurações de provedor para criar, ler, atualizar, desabilitar, habilitar e excluir as suas conexões.

Registro de configurações de executor

O Flowker mantém um registro com os cadastros de configuração de executor. O registro expõe quatro operações:

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

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

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

O corpo da atualização não inclui status, mas a operação de listagem o aceita como filtro de consulta. A atualização vale para cadastros no status unconfigured ou configured. A exclusão vale para cadastros no status unconfigured, configured ou disabled. Nenhuma operação desta versão move um cadastro para tested, active ou disabled. A tabela lista esses valores porque as respostas os informam e o filtro da listagem os aceita.

Templates

Os templates de workflow são padrões de workflow prontos 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 pelo Tracer e cria a transação no Midaz quando o Tracer a aprova. Cada template tem um schema de parâmetros que define quais entradas ele espera (por exemplo, qual configuração de provedor usar, valores de limiar). Quando o Flowker consegue recuperar as configurações de provedor ativas, ele enriquece os campos de parâmetro referenciados com opções selecionáveis. Se a consulta não estiver disponível ou falhar, ele devolve o schema original. Para inspecionar um template:

Liste os templates do catálogo.
Obtenha o detalhe do template para ver o schema de parâmetros dele.
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 gatilho normalmente inicia uma nova execução. Uma nova tentativa que reutiliza uma chave de idempotência existente devolve a execução já existente em vez de criar outra. Cada execução acompanha:

executionId: identificador único desta rodada.
status: estado atual (pending, running, completed ou failed).
stepResults: a saída de cada nó de executor, condicional ou ação executado, em ordem. Os nós de gatilho começam o percurso do grafo e não criam registros de etapa de execução.
finalOutput: o valor final gravado para a execução. Quando uma ação set_output produz um objeto, o Flowker usa esse objeto. Caso contrário, o Flowker devolve o contexto acumulado do workflow.

Use Obter status da execução para acompanhar o progresso e Obter resultados da execução para recuperar a saída completa.

O endpoint de status devolve o registro da execução, com o status atual dele. O endpoint dedicado de resultados (GET /v1/executions/{id}/results) devolve status, stepResults e finalOutput quando presentes. Uma etapa com falha pode incluir errorMessage. Esta resposta não tem campo de detalhes de erro no nível superior.

Idempotência

As requisições de execução direta exigem uma string Idempotency-Key não vazia. O Flowker não impõe o formato UUID. O header do webhook é opcional. Se o Flowker recebe uma segunda requisição com a mesma Idempotency-Key, ele devolve a execução já existente em vez de criar outra. Uma repetição direta devolve HTTP 200 e inclui idempotencyReplayed na resposta.

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

Use uma chave nova quando você quer de propósito uma nova execução. Reutilize a mesma chave apenas ao repetir exatamente a mesma requisição.

Dashboard

A API do Dashboard fornece resumos agregados dos seus workflows e execuções. Use-a sempre que você precisar de uma visão geral da saúde do sistema sem consultar execuções individuais.

Resumo de workflows devolve os totais e a divisão por status (draft, active, inactive).
Resumo de execuções devolve os totais e a divisão por status, com filtros opcionais de intervalo de tempo e de 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 de falha ao longo do tempo para notar cedo uma degradação.
Montar páginas de status: mostre o throughput dos workflows e as métricas de sucesso em dashboards internos ou voltados ao cliente.
Alertar em picos de taxa de falha: compare failed / total com um limiar para disparar alertas antes que os problemas se espalhem.

Como tudo se encaixa

Os conceitos do Flowker se apoiam uns nos outros em uma sequência clara:

Explore o catálogo para descobrir os provedores, os executores de catálogo, os gatilhos e os templates disponíveis.
Crie configurações de provedor para conectar o Flowker a instâncias ativas de serviços externos.
Defina workflows: cada nó de executor nomeia um executor de catálogo e a configuração de provedor pela qual ele chama.
Execute workflows para rodar o seu processo de negócio e recuperar os resultados.
Monitore: use o dashboard para os resumos operacionais e a API de execuções para o detalhe por etapa.

Siga o guia de primeiros passos para rodar o seu primeiro workflow de ponta a ponta.

Visão geral

Guias

Console

Operações

Conceitos centrais

Workflows

Nós e arestas

Catálogo

Configurações de provedor

Como um workflow chega até ela

Registro de configurações de executor

Templates

Execuções

Idempotência

Dashboard

Como tudo se encaixa

​Workflows

​Nós e arestas

​Catálogo

​Configurações de provedor

​Como um workflow chega até ela

​Registro de configurações de executor

​Templates

​Execuções

​Idempotência

​Dashboard

​Como tudo se encaixa

Workflows

Nós e arestas

Catálogo

Configurações de provedor

Como um workflow chega até ela

Registro de configurações de executor

Templates

Execuções

Idempotência

Dashboard

Como tudo se encaixa