Primeros pasos con Flowker

Ejecuta Flowker localmente y lanza tu primer workflow desde la API en cuestión de minutos con esta guía práctica pensada para desarrolladores.

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?.

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.26.5+	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:

cd flowker

Instala las herramientas de desarrollo y crea el archivo de entorno:

make dev-setup

Luego inicia el stack local (MongoDB + Flowker en el puerto 4021):

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 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: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": {
          "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 .

La respuesta confirma que el workflow fue creado con estado draft:

{
  "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.

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.

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.

{
  "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:4021/v1/executions/019c96a0-10ce-75fc-a273-dc799079a99c/results | jq .

La respuesta incluye el estado de cada paso y la salida 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": "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 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 make dev-setup copia en su lugar lo define, así que la superficie está disponible en un stack local; donde la variable no está definida las rutas no se montan y devuelven 404.

Superficie	URL
Documentación interactiva	http://localhost:4021/openapi/docs
Spec (JSON)	http://localhost:4021/openapi/openapi.json
Spec (YAML)	http://localhost:4021/openapi/openapi.yaml

Usa la interfaz de documentación 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 está deshabilitada por defecto.

En staging, producción o cualquier entorno con Access Manager habilitado (PLUGIN_AUTH_ENABLED=true), todos los endpoints /v1/* requieren un Bearer token en el header Authorization:

curl -H "Authorization: Bearer <token>" 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 provider (conectar con providers KYC, motores de fraude, servicios de pago)
• Diseñar flujos condicionales con nodes conditional que evalúan expresiones sobre las salidas de cada paso y enrutan por el edge cuyo sourceHandle coincide
• 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.