Primeiros passos com o Flowker

Este guia é destinado a desenvolvedores. Se você está procurando uma visão geral de nível de negócio sobre o que o Flowker faz, veja O que é o Flowker?.

O Flowker é um motor de orquestração de workflows projetado para modelar, executar e escalar processos de negócio com precisão. Neste guia, você vai rodar o Flowker localmente e executar seu primeiro workflow — da criação à obtenção dos resultados. 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, verifique se o 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). Nenhuma infraestrutura externa é necessária para este guia.

Passo 1: Obtenha o Flowker e configure o projeto

O Flowker está disponível para clientes licenciados; seu repositório é mantido internamente. Os passos a seguir presumem que você já tem acesso aos arquivos do projeto Flowker necessários.

Com acesso aos arquivos do projeto, navegue até o diretório Flowker e 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 mostrar que o servidor está rodando, o Flowker estará disponível em http://localhost:4021.

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

Passo 2: Crie seu primeiro workflow

Workflows definem como o seu processo de negócio se comporta — quais passos são executados, em qual ordem e sob quais condições. Cada workflow é composto por nodes (os passos) e edges (as conexões entre eles). Crie um workflow com um trigger de webhook e uma ação de log:

curl -s -X POST http://localhost:4021/v1/workflows \
  -H "Content-Type: application/json" \
  -d '{
    "name": "meu-primeiro-workflow",
    "description": "Um workflow simples com um trigger e uma ação.",
    "nodes": [
      {
        "id": "trigger-1",
        "type": "trigger",
        "name": "Início",
        "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": "Registrar evento",
        "position": { "x": 200, "y": 0 },
        "data": { "action": "log" }
      }
    ],
    "edges": [
      {
        "id": "e1",
        "source": "trigger-1",
        "target": "log-event"
      }
    ]
  }' | jq .

A resposta confirma que o workflow foi criado com status draft:

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

Guarde o valor do id — você vai precisar dele nos próximos passos.

Novos workflows são sempre criados com status draft. Um workflow precisa ter pelo menos um node.

No Flowker, os nodes representam os passos individuais do seu workflow — o que em termos de negócio você chamaria de tarefas. Os edges definem a ordem em que esses passos são executados.

Passo 3: Ative o workflow

Um workflow precisa ser ativado antes de poder ser executado. 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 .

Uma vez ativado, a estrutura do workflow fica bloqueada e não pode ser editada diretamente. Para fazer alterações, 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. O header Idempotency-Key é obrigatório para garantir retentativas 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": "olá do meu primeiro workflow"
    }
  }' | jq .

A resposta retorna um executionId e um status de running:

{
  "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 caso de reenvio.

Passo 5: Consulte os resultados

Obtenha o resultado de uma execução do workflow:

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

A resposta inclui o status de cada passo 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": "olá do meu primeiro workflow"
    }
  },
  "startedAt": "2026-03-18T14:35:00Z",
  "completedAt": "2026-03-18T14:35:00Z"
}

Se a execução ainda estiver em andamento, este endpoint retorna um status 422. Consulte /v1/executions/{executionId} para verificar o status atual antes de solicitar os resultados.

Explore a API localmente

O Flowker serve sua descrição OpenAPI 3.1 e uma interface de documentação interativa quando SWAGGER_ENABLED=true. O arquivo de ambiente de exemplo que o make dev-setup copia para o lugar define essa variável, então a superfície fica disponível em um stack local; onde a variável não está definida as rotas não são montadas e retornam 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 request e response

Uma nota sobre autenticação

No ambiente de desenvolvimento local (make dev), a autenticação está 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://seu-host-flowker/v1/workflows

Próximos passos

Você agora tem um ambiente Flowker funcional e já executou seu primeiro workflow. A partir daqui, você pode:

Modelar processos de negócio reais usando diferentes tipos de nodes: trigger, executor, conditional e action
Integrar sistemas externos via configurações de provider (conecte-se a providers de KYC, engines de fraude, serviços de pagamento)
Projetar fluxos condicionais com nodes conditional que avaliam expressões sobre as saídas dos passos e roteiam pelo edge cujo sourceHandle corresponde
Monitorar execuções usando os endpoints de status e resultados de execução

O Flowker foi projetado para evoluir de fluxos simples para orquestração em nível de produção sem alterar o modelo base.