Primeros pasos con Flowker

Esta guía es para desarrolladores. Si buscas una descripción general orientada al negocio de lo que hace Flowker, consulta ¿Qué es 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:

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

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:

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:

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

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.

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ó:

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

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:

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

curl -H "Authorization: Bearer <token>" 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.

Primeros pasos

API de Catálogo

API de Workflows

API de Programación

API de Ejecuciones

API de Dashboards

API de Configuraciones de Executor

API de Configuraciones de Provider

API de Registro de Esquemas

API de Esquemas OpenAPI

API de Esquemas XSD

API de Webhooks

Manejo de errores

Primeros pasos con Flowker

Requisitos previos

Paso 1: Obtén Flowker y configura el proyecto

Paso 2: Crea tu primer workflow

Paso 3: Activa el workflow

Paso 4: Ejecuta el workflow

Paso 5: Revisa los resultados de la ejecución

Explora la API en tu entorno local

Una nota sobre la autenticación

Próximos pasos

​Requisitos previos

​Paso 1: Obtén Flowker y configura el proyecto

​Paso 2: Crea tu primer workflow

​Paso 3: Activa el workflow

​Paso 4: Ejecuta el workflow

​Paso 5: Revisa los resultados de la ejecución

​Explora la API en tu entorno local

​Una nota sobre la autenticación

​Próximos pasos

Requisitos previos

Paso 1: Obtén Flowker y configura el proyecto

Paso 2: Crea tu primer workflow

Paso 3: Activa el workflow

Paso 4: Ejecuta el workflow

Paso 5: Revisa los resultados de la ejecución

Explora la API en tu entorno local

Una nota sobre la autenticación

Próximos pasos