Primeiros passos com o Flowker

Este guia é para desenvolvedores. Se você está procurando uma visão geral de negócio do que o Flowker faz, veja O que é o Flowker?.

O Flowker é um mecanismo de orquestração de workflows. Use-o para modelar, executar e escalar processos de negócio. Você vai rodar o Flowker localmente e executar seu primeiro workflow, da criação até a recuperação do resultado. Ao final, você terá um ambiente funcional para validar fluxos de automação e integrá-los aos seus sistemas.

Pré-requisitos

Antes de começar, confirme que seu ambiente está pronto:

Ferramenta	Versão mínima	Comando de verificação
Go	1.26.5+	`go version`
Docker	24+	`docker --version`
Docker Compose	2.20+	`docker compose version`
Make	Instalado	`make --version`

O Flowker roda localmente usando Docker para seu banco de dados (MongoDB). Este guia não precisa de infraestrutura externa.

Passo 1: Obtenha o Flowker e configure o projeto

O Flowker está disponível para clientes licenciados. Seu repositório permanece interno. Os passos abaixo supõem que você já tem acesso aos arquivos necessários do projeto Flowker.

A partir do diretório do projeto Flowker, prepare o ambiente de desenvolvimento:

cd flowker

Instale as ferramentas de desenvolvimento e crie o arquivo de ambiente:

make dev-setup

Em seguida, inicie a stack local (MongoDB + Flowker na porta 4021):

make dev

Quando a saída informar um servidor em execução, o Flowker estará disponível em http://localhost:4021.

O comando make dev inicia o MongoDB, gera a documentação da API e roda a aplicação Flowker com autenticação desabilitada, para que você possa testar livremente durante o desenvolvimento.

Passo 2: Crie seu primeiro workflow

Workflows definem como seu processo de negócio se comporta: quais etapas rodam, em qual ordem e sob quais condições. Cada workflow tem nós (as etapas) e arestas (as conexões entre elas). Crie um workflow com um gatilho de webhook e uma ação de log:

curl -s -X POST http://localhost:4021/v1/workflows \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-workflow",
    "description": "A simple workflow with one trigger and one action.",
    "nodes": [
      {
        "id": "trigger-1",
        "type": "trigger",
        "name": "Start",
        "position": { "x": 0, "y": 0 },
        "data": {
          "triggerType": "webhook",
          "path": "my-first-workflow",
          "method": "POST",
          "input_contract": "open",
          "format": "json"
        }
      },
      {
        "id": "log-event",
        "type": "action",
        "name": "Log event",
        "position": { "x": 200, "y": 0 },
        "data": { "action": "log" }
      }
    ],
    "edges": [
      {
        "id": "e1",
        "source": "trigger-1",
        "target": "log-event"
      }
    ]
  }' | jq .

A resposta confirma o novo workflow no status draft:

{
  "id": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
  "name": "my-first-workflow",
  "status": "draft"
}

Guarde o valor de id. Você vai precisar dele nos próximos passos.

Todo novo workflow começa no status draft. Um workflow deve ter pelo menos um nó.

No Flowker, os nós representam as etapas individuais do seu workflow (o que você poderia chamar de tarefas em termos de negócio). As arestas definem a ordem em que essas etapas rodam.

Passo 3: Ative o workflow

Você deve ativar um workflow antes de poder executá-lo. Isso transiciona o workflow de draft para active.

curl -s -X POST http://localhost:4021/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/activate \
  -H "Content-Type: application/json" | jq .

Depois da ativação, a estrutura de um workflow permanece travada. Você não pode editá-la diretamente. Para fazer mudanças, clone o workflow, modifique o clone e ative a nova versão.

Passo 4: Execute o workflow

Dispare a execução de um workflow enviando dados de entrada. Você deve enviar o header Idempotency-Key para tornar as novas tentativas seguras.

curl -s -X POST http://localhost:4021/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/executions \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b" \
  -d '{
    "inputData": {
      "message": "hello from my first workflow"
    }
  }' | jq .

A resposta confirma que a execução foi iniciada:

{
  "executionId": "019c96a0-10ce-75fc-a273-dc799079a99c",
  "workflowId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
  "status": "running",
  "startedAt": "2026-03-18T14:35:00Z"
}

Guarde o executionId para o próximo passo.

O header Idempotency-Key é obrigatório. Use um UUID único por requisição para evitar execuções duplicadas em uma nova tentativa.

Passo 5: Verifique os resultados da execução

Recupere o resultado de uma execução de workflow:

curl -s http://localhost:4021/v1/executions/019c96a0-10ce-75fc-a273-dc799079a99c/results | jq .

A resposta inclui o status de cada etapa e a saída final:

{
  "executionId": "019c96a0-10ce-75fc-a273-dc799079a99c",
  "workflowId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
  "status": "completed",
  "stepResults": [
    {
      "stepNumber": 1,
      "stepName": "action_log-event",
      "nodeId": "log-event",
      "status": "completed",
      "output": { "action": "log" },
      "executedAt": "2026-03-18T14:35:00Z",
      "durationMs": 12
    }
  ],
  "finalOutput": {
    "workflow": {
      "message": "hello from my first workflow"
    }
  },
  "startedAt": "2026-03-18T14:35:00Z",
  "completedAt": "2026-03-18T14:35:00Z"
}

Enquanto a execução roda, esse endpoint retorna um status 422. Consulte /v1/executions/{executionId} para checar o status atual antes de solicitar os resultados.

Explore a API localmente

O Flowker expõe sua descrição OpenAPI 3.1 e uma interface interativa de documentação quando SWAGGER_ENABLED=true. O arquivo de ambiente de exemplo que make dev-setup copia já define essa variável, então a superfície fica disponível em uma stack local. Onde a variável não estiver definida, o Flowker não monta as rotas e retorna 404.

Superfície	URL
Documentação interativa	http://localhost:4021/openapi/docs
Spec (JSON)	`http://localhost:4021/openapi/openapi.json`
Spec (YAML)	`http://localhost:4021/openapi/openapi.yaml`

Use a interface de documentação para:

Inspecionar todos os endpoints disponíveis
Testar requisições de forma interativa
Entender as estruturas de requisição e resposta

Uma nota sobre autenticação

No ambiente de desenvolvimento local (make dev), a autenticação vem desabilitada por padrão. Em staging, produção, ou qualquer ambiente com o Access Manager habilitado (PLUGIN_AUTH_ENABLED=true), todos os endpoints /v1/* exigem um Bearer token no header Authorization:

curl -H "Authorization: Bearer <token>" http://your-flowker-host/v1/workflows

Próximos passos

Agora você tem um ambiente Flowker em execução e já executou seu primeiro workflow. A partir daqui, você pode:

Modelar processos de negócio reais usando diferentes tipos de nó: trigger, executor, conditional e action
Integrar sistemas externos por meio de configurações de provedor (conecte-se a provedores de KYC, mecanismos antifraude, serviços de pagamento)
Projetar fluxos condicionais com nós condicionais que avaliam expressões sobre as saídas das etapas e roteiam pela aresta sourceHandle correspondente
Monitorar execuções usando os endpoints de status e resultados de execução

O modelo central é o mesmo para fluxos simples e para orquestração em nível de produção.