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.22+ | 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.
Comece clonando o repositório e preparando o ambiente de desenvolvimento:
git clone https://github.com/LerianStudio/flowker.git
cd flowker
http://localhost:4000.
O comando make dev inicia o MongoDB, gera a documentação da API e executa o Flowker com a autenticação por API key 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:4000/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": { "triggerId": "webhook" }
},
{
"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 .
draft:
{
"id": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
"name": "meu-primeiro-workflow",
"status": "draft"
}
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:4000/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:4000/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 .
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"
}
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:4000/v1/executions/019c96a0-10ce-75fc-a273-dc799079a99c/results | jq .
{
"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 fornece uma interface interativa Swagger UI para testes e exploração: http://localhost:4000/swagger/index.html
Use-a 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 por API key está desabilitada por padrão.
Em staging, produção ou qualquer ambiente configurado, todos os endpoints /v1/* exigem o header X-API-Key:
curl -H "X-API-Key: sua-api-key" 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 executor (conecte-se a provedores de KYC, engines de fraude, serviços de pagamento)
- Projetar fluxos condicionais com edges que avaliam expressões baseadas nas saídas dos passos
- 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. 
