> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Primeros pasos con Flowker
**Esta guía está dirigida a desarrolladores.** Si buscas una visión general a nivel de negocio de lo que hace Flowker, consulta [¿Qué es Flowker?](/es/flowker/what-is-flowker).
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: Obtén Flowker y configura el proyecto
***
Flowker está disponible para clientes con licencia; su repositorio se mantiene internamente. Los pasos a continuación asumen que ya tienes acceso a los archivos del proyecto Flowker requeridos.
Desde el directorio del proyecto Flowker, prepara el entorno de desarrollo:
```bash theme={null}
cd flowker
```
Instala las herramientas de desarrollo y crea el archivo de entorno:
```bash theme={null}
make dev-setup
```
Luego inicia el stack local (MongoDB + Flowker en el puerto 4021):
```bash theme={null}
make dev
```
Una vez que la salida muestre que el servidor está corriendo, Flowker estará disponible en `http://localhost:4021`.
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:
```bash theme={null}
curl -s -X POST http://localhost:4021/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 .
```
La respuesta confirma que el workflow fue creado con estado `draft`:
```json theme={null}
{
"id": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
"name": "mi-primer-workflow",
"status": "draft"
}
```
Guarda el valor del `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.
```bash theme={null}
curl -s -X POST http://localhost:4021/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/activate \
-H "Content-Type: application/json" | jq .
```
Esto transiciona el workflow de `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.
```bash theme={null}
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": "hola desde mi primer workflow"
}
}' | jq .
```
La respuesta devuelve un `executionId` y un `status` de `running`. Guarda el `executionId` para el siguiente paso.
```json theme={null}
{
"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:
```bash theme={null}
curl -s http://localhost:4021/v1/executions/019c96a0-10ce-75fc-a273-dc799079a99c/results | jq .
```
La respuesta incluye el estado de cada paso y la salida final:
```json theme={null}
{
"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:4021/swagger/index.html](http://localhost:4021/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`:
```bash theme={null}
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.