Flowker es un motor de orquestación de workflows diseñado para modelar, ejecutar y escalar procesos de negocio con precisión. En esta guía, ejecutarás Flowker localmente y correrás tu primer workflow, desde la creación hasta la obtención de resultados.
Requisitos previos
Antes de comenzar, asegúrate de que tu entorno esté listo:
| Herramienta | Versión mínima | Comando de verificación |
|---|
| Go | 1.22+ | go version |
| Docker | 24+ | docker --version |
| Docker Compose | 2.20+ | docker compose version |
| Make | Instalado | make --version |
Flowker se ejecuta localmente usando Docker para su base de datos (MongoDB). No se necesita infraestructura externa para esta guía.
Paso 1: Clona y configura el proyecto
Comienza clonando el repositorio y preparando el entorno de desarrollo:
git clone https://github.com/LerianStudio/flowker.git
cd flowker
http://localhost:4000.
El comando make dev inicia MongoDB, genera la documentación de la API y ejecuta la aplicación Flowker con la autenticación por API key deshabilitada, para que puedas probar libremente durante el desarrollo.
Paso 2: Crea tu primer workflow
Los workflows definen cómo se comporta tu proceso de negocio — qué pasos se ejecutan, en qué orden y bajo qué condiciones. Cada workflow está compuesto por nodes (los pasos) y edges (las conexiones entre ellos).
Crea un workflow con un trigger de webhook y una acción de log:
curl -s -X POST http://localhost:4000/v1/workflows \
-H "Content-Type: application/json" \
-d '{
"name": "mi-primer-workflow",
"description": "Un workflow simple con un trigger y una acción.",
"nodes": [
{
"id": "trigger-1",
"type": "trigger",
"name": "Inicio",
"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": "mi-primer-workflow",
"status": "draft"
}
id — lo necesitarás en los siguientes pasos.
Los nuevos workflows siempre se crean con estado draft. Un workflow debe tener al menos un node.
En Flowker, los nodes representan los pasos individuales de tu workflow — lo que en términos de negocio podrías llamar tareas. Los edges definen el orden en que se ejecutan esos pasos.
Paso 3: Activa el workflow
Un workflow debe activarse antes de poder ejecutarse. La activación transiciona el estado de draft a active y bloquea su estructura.
curl -s -X POST http://localhost:4000/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/activate \
-H "Content-Type: application/json" | jq .
draft a active.
Una vez activado, un workflow no puede editarse directamente. Para hacer cambios, clónalo, modifica el clon y activa la nueva versión.
Paso 4: Ejecuta el workflow
Inicia una ejecución del workflow enviando datos de entrada. El header Idempotency-Key es obligatorio para garantizar reintentos seguros.
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": "hola desde mi primer workflow"
}
}' | jq .
executionId y un status de running. Guarda el executionId para el siguiente paso.
{
"executionId": "019c96a0-10ce-75fc-a273-dc799079a99c",
"workflowId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
"status": "running",
"startedAt": "2026-03-18T14:35:00Z"
}
El header Idempotency-Key es obligatorio. Usa un UUID único por solicitud para evitar ejecuciones duplicadas en caso de reintento.
Paso 5: Consulta los resultados
Obtén el resultado de la ejecución del 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": "hola desde mi primer workflow"
}
},
"startedAt": "2026-03-18T14:35:00Z",
"completedAt": "2026-03-18T14:35:00Z"
}
Si la ejecución aún está en curso, este endpoint devuelve un estado 422. Consulta /v1/executions/{executionId} para verificar el estado actual antes de solicitar los resultados.
Explora la API localmente
Flowker proporciona una interfaz interactiva de Swagger UI para pruebas y exploración: http://localhost:4000/swagger/index.html
Úsala para:
- Inspeccionar todos los endpoints disponibles
- Probar solicitudes de forma interactiva
- Comprender las estructuras de solicitud y respuesta
Nota sobre autenticación
En el entorno de desarrollo local (make dev), la autenticación por API key está deshabilitada por defecto.
En staging, producción o cualquier entorno configurado, todos los endpoints /v1/* requieren el header X-API-Key:
curl -H "X-API-Key: tu-api-key" http://tu-host-flowker/v1/workflows
¿Qué sigue?
Ya tienes un entorno Flowker en funcionamiento y has ejecutado tu primer workflow.
Desde aquí, puedes:
- Modelar procesos de negocio reales usando distintos tipos de nodes:
trigger, executor, conditional y action
- Integrar sistemas externos mediante configuraciones de executor (conectar con proveedores KYC, motores de fraude, servicios de pago)
- Diseñar flujos condicionales con edges que evalúen expresiones basadas en las salidas de cada paso
- Monitorear ejecuciones usando los endpoints de estado y resultados de ejecución
Flowker está diseñado para pasar de flujos simples a orquestación de nivel productivo sin cambiar el modelo central. 
