> ## 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
> Ejecuta Flowker en tu entorno local, crea tu primer workflow, ejecútalo y obtén los resultados. Un inicio rápido práctico para desarrolladores que usan el motor de orquestación.
**Esta guía es para desarrolladores.** Si buscas una descripción general orientada al negocio de lo que hace Flowker, consulta [¿Qué es Flowker?](/es/products/flowker/what-is-flowker).
Flowker es un motor de orquestación de workflows. Úsalo para modelar, ejecutar y escalar procesos de negocio.
Vas a ejecutar Flowker en tu entorno local y tu primer workflow, desde la creación hasta la obtención del resultado. Al final, tendrás un entorno funcional para validar flujos de automatización e integrarlos en tus sistemas.
## Requisitos previos
***
Antes de empezar, confirma que tu entorno esté listo:
| Herramienta | Versión mínima | Comando de verificación |
| -------------- | -------------- | ------------------------ |
| Go | 1.26.5+ | `go version` |
| Docker | 24+ | `docker --version` |
| Docker Compose | 2.20+ | `docker compose version` |
| Make | Instalado | `make --version` |
Flowker se ejecuta en tu entorno local usando Docker para su base de datos (MongoDB). Esta guía no necesita infraestructura externa.
## Paso 1: Obtén Flowker y configura el proyecto
***
Flowker está disponible para clientes con licencia. Su repositorio permanece interno. Los pasos siguientes suponen que ya tienes acceso a los archivos del proyecto de Flowker que se necesitan.
Desde el directorio del proyecto de 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
```
Cuando la salida indique que el servidor está en ejecución, Flowker está disponible en `http://localhost:4021`.
El comando `make dev` inicia MongoDB, genera la documentación de la API y ejecuta la aplicación de Flowker con la autenticación deshabilitada, para que puedas hacer pruebas 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 tiene **nodos** (los pasos) y **aristas** (las conexiones entre ellos).
Crea un workflow con un disparador 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": "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 .
```
La respuesta confirma el nuevo workflow en estado `draft`:
```json theme={null}
{
"id": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
"name": "my-first-workflow",
"status": "draft"
}
```
Guarda el valor `id`. Lo necesitarás en los próximos pasos.
Todo workflow nuevo empieza en estado `draft`. Un workflow debe tener al menos un nodo.
En Flowker, los **nodos** representan los pasos individuales de tu workflow (lo que en términos de negocio podrías llamar tareas). Las **aristas** definen el orden en que se ejecutan esos pasos.
## Paso 3: Activa el workflow
***
Debes activar un workflow antes de poder ejecutarlo. Esto hace que el workflow pase de `draft` a `active`.
```bash theme={null}
curl -s -X POST http://localhost:4021/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/activate \
-H "Content-Type: application/json" | jq .
```
Después de la activación, la estructura del workflow queda bloqueada. No puedes editarla directamente. Para hacer cambios, clónalo, modifica el clon y activa la nueva versión.
## Paso 4: Ejecuta el workflow
***
Dispara una ejecución del workflow enviando datos de entrada. Debes enviar el header `Idempotency-Key` para que los reintentos sean 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": "hello from my first workflow"
}
}' | jq .
```
La respuesta confirma que la ejecución empezó:
```json theme={null}
{
"executionId": "019c96a0-10ce-75fc-a273-dc799079a99c",
"workflowId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
"status": "running",
"startedAt": "2026-03-18T14:35:00Z"
}
```
Guarda el `executionId` para el siguiente paso.
El header `Idempotency-Key` es obligatorio. Usa un UUID único por solicitud para evitar ejecuciones duplicadas al reintentar.
## Paso 5: Revisa los resultados de la ejecución
***
Obtén el resultado de una 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 el resultado 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": "hello from my first workflow"
}
},
"startedAt": "2026-03-18T14:35:00Z",
"completedAt": "2026-03-18T14:35:00Z"
}
```
Mientras la ejecución está en curso, este endpoint devuelve un estado `422`. Consulta periódicamente `/v1/executions/{executionId}` para revisar el estado actual antes de solicitar los resultados.
## Explora la API en tu entorno local
***
Flowker sirve su descripción OpenAPI 3.1 y una interfaz de documentación interactiva cuando `SWAGGER_ENABLED=true`. El archivo de entorno de ejemplo que copia `make dev-setup` establece esta variable, por lo que la superficie está disponible en un stack local. En cualquier lugar donde la variable no esté definida, Flowker no monta las rutas y devuelve `404`.
| Superficie | URL |
| ------------------------- | ------------------------------------------------------------------------ |
| Documentación interactiva | [http://localhost:4021/openapi/docs](http://localhost:4021/openapi/docs) |
| Especificación (JSON) | `http://localhost:4021/openapi/openapi.json` |
| Especificación (YAML) | `http://localhost:4021/openapi/openapi.yaml` |
Usa la interfaz de documentación para:
* Inspeccionar todos los endpoints disponibles
* Probar solicitudes de forma interactiva
* Entender las estructuras de solicitud y respuesta
## Una nota sobre la autenticación
***
En el entorno de desarrollo local (`make dev`), la autenticación está deshabilitada de forma predeterminada.
En staging, en producción, o en cualquier entorno con Access Manager habilitado (`PLUGIN_AUTH_ENABLED=true`), todos los endpoints `/v1/*` requieren un token bearer en el header `Authorization`:
```bash theme={null}
curl -H "Authorization: Bearer " http://your-flowker-host/v1/workflows
```
## Próximos pasos
***
Ahora tienes un entorno de Flowker en ejecución y ejecutaste tu primer workflow.
Desde aquí, puedes:
* **Modelar procesos de negocio reales** usando diferentes tipos de nodo: `trigger`, `executor`, `conditional` y `action`
* **Integrar sistemas externos** mediante configuraciones de proveedor (conéctate a proveedores de KYC, motores de fraude, servicios de pago)
* **Diseñar flujos condicionales** con nodos condicionales que evalúan expresiones sobre los resultados de los pasos y enrutan a través de la arista `sourceHandle` que coincide
* **Monitorear las ejecuciones** usando los endpoints de estado y resultados de la ejecución
El modelo central es el mismo para flujos simples y para orquestación de nivel de producción.