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

# Conceptos fundamentales

> Comprende los componentes de Flowker: workflows, nodos, edges, catálogo, proveedores, plantillas, ejecuciones, dashboard y auditoría.

Flowker se construye sobre un conjunto de conceptos interconectados. Comprender cómo se relacionan entre sí te ayudará a diseñar, configurar y ejecutar workflows de manera efectiva. El diagrama al final de esta página muestra cómo todo encaja.

## Workflows

***

Un workflow es la definición de un proceso de negocio — la secuencia de pasos que Flowker sigue para completar una operación.

Cada workflow tiene un ciclo de vida con tres estados posibles:

| Estado     | Descripción                                        |
| ---------- | -------------------------------------------------- |
| `draft`    | Creado y editable. Aún no se puede ejecutar.       |
| `active`   | Listo para ejecutar. La estructura está bloqueada. |
| `inactive` | Desactivado. No se aceptan nuevas ejecuciones.     |

Para cambiar el estado de un workflow, usa los endpoints [activar](/es/reference/flowker/activate-workflow), [desactivar](/es/reference/flowker/deactivate-workflow) y [mover a draft](/es/reference/flowker/move-workflow-to-draft).

## Nodes y edges

***

Los nodes son los pasos individuales de un workflow — lo que en términos de negocio llamarías **tareas**. Cada node es una unidad de trabajo: recibir un evento, llamar a un servicio, evaluar una condición o realizar una acción.

Flowker admite cuatro tipos de node:

| Tipo          | Propósito                                                    | Cuándo usarlo                                                        |
| ------------- | ------------------------------------------------------------ | -------------------------------------------------------------------- |
| `trigger`     | Punto de entrada del workflow                                | Siempre el primer node. Inicia la ejecución cuando ocurre un evento. |
| `executor`    | Llama a un servicio externo mediante un executor configurado | Cuando necesitas llamar a una API o integración externa.             |
| `conditional` | Bifurca la ejecución según condiciones                       | Cuando el siguiente paso depende del resultado del anterior.         |
| `action`      | Ejecuta una acción integrada (log, transform, etc.)          | Para operaciones nativas que no requieren llamadas externas.         |

Los **edges** conectan nodes y definen el orden de ejecución. Un edge puede llevar una condición: el siguiente node solo se ejecuta si la condición es verdadera.

## Catálogo

***

El catálogo es el registro de solo lectura de todos los providers, executors y triggers integrados disponibles en Flowker. No puedes crear ni modificar entradas del catálogo — solo descubrirlas.

Antes de configurar cualquier integración, explora el catálogo para ver qué está disponible:

* Los **executors** son las capacidades específicas que puedes invocar en un node (p. ej., solicitudes HTTP, transformaciones de datos).
* Los **triggers** definen los tipos de eventos que pueden iniciar un workflow (p. ej., webhooks).

Usa estos endpoints para explorar lo que está disponible:

* [Listar executors del catálogo](/es/reference/flowker/list-catalog-executors) y [Listar triggers del catálogo](/es/reference/flowker/list-catalog-triggers) para descubrir tipos de executor y trigger.
* [Listar providers del catálogo](/es/reference/flowker/list-catalog-providers) (`GET /v1/catalog/providers`) para listar todos los providers disponibles.
* [Obtener provider del catálogo](/es/reference/flowker/get-catalog-provider) (`GET /v1/catalog/providers/{id}`) para obtener los detalles de un provider específico.
* [Listar executors por provider](/es/reference/flowker/list-executors-by-provider) (`GET /v1/catalog/providers/{id}/executors`) para listar los executors disponibles para un provider específico.

## Configuraciones

***

Antes de usar un executor en un workflow, debes configurarlo. Una **configuración de executor** define cómo Flowker se conecta a un servicio externo — incluyendo la URL base, las credenciales de autenticación y los endpoints HTTP específicos a llamar.

Las configuraciones de executor pasan por un ciclo de vida:

| Estado         | Descripción                                              |
| -------------- | -------------------------------------------------------- |
| `unconfigured` | Creada pero aún no configurada con detalles de conexión. |
| `configured`   | Detalles de conexión proporcionados, lista para probar.  |
| `tested`       | Prueba de conectividad exitosa.                          |
| `active`       | Lista para ser usada en ejecuciones de workflows.        |
| `disabled`     | Temporalmente fuera de servicio.                         |

Usa los endpoints de [Configuraciones de executor](/es/reference/flowker/list-executor-configurations) para configurar y gestionar tus integraciones.

## Configuraciones de provider

***

Flowker usa un modelo de tres capas para integraciones externas:

| Capa                          | Qué es                                                                     | Naturaleza                                           |
| ----------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------- |
| **Provider**                  | Un tipo de servicio externo (p. ej., Midaz, Tracer).                       | Estático — definido en el catálogo.                  |
| **Configuración de Provider** | Una instancia configurada de un provider con credenciales y URL base.      | Dinámica — tú la creas y gestionas.                  |
| **Configuración de Executor** | Una operación específica en un provider, con endpoints y mapeos de campos. | Dinámica — referencia una configuración de provider. |

Una **configuración de provider** conecta Flowker a una instancia activa de un servicio externo. Proporcionas la URL base, las credenciales de autenticación y cualquier configuración específica del provider. La configuración se valida contra el JSON Schema del provider en el catálogo.

Las configuraciones de provider tienen dos estados: `active` (en uso) y `disabled` (temporalmente offline). Puedes [probar la conectividad](/es/reference/flowker/test-provider-configuration) en cualquier momento para verificar que la conexión funcione.

Usa los endpoints de [Configuraciones de provider](/es/reference/flowker/list-provider-configurations) para crear, gestionar y probar tus conexiones con providers.

## Templates

***

Los templates de workflow son patrones pre-construidos disponibles en el catálogo. En lugar de definir un workflow desde cero, puedes seleccionar un template, completar sus parámetros y crear un workflow listo para usar en segundos.

Cada template tiene un schema de parámetros que define qué entradas espera (p. ej., qué configuración de provider usar, valores de umbral). Cuando consultas un template, el schema se **enriquece dinámicamente** — los campos que referencian configuraciones de provider se completan con tus configuraciones activas, para que puedas elegir de una lista en lugar de ingresar UUIDs manualmente.

Para usar un template:

1. [Explora los templates disponibles](/es/reference/flowker/list-catalog-templates) en el catálogo.
2. [Consulta el detalle del template](/es/reference/flowker/get-catalog-template) para ver su schema de parámetros.
3. Opcionalmente [valida tus parámetros](/es/reference/flowker/validate-catalog-template-params) antes de crear.
4. [Crea un workflow a partir del template](/es/reference/flowker/create-workflow-from-template).

El workflow resultante se crea con estado `draft`, para que puedas revisarlo y ajustarlo antes de activar.

## Ejecuciones

***

Una ejecución es una instancia en tiempo de ejecución de un workflow. Cada vez que activas un workflow, Flowker crea una nueva ejecución y procesa sus nodes en orden.

Cada ejecución registra:

* `executionId` — Identificador único de esta ejecución.
* `status` — Estado actual: `pending`, `running`, `completed` o `failed`.
* `stepResults` — La salida de cada node ejecutado, en orden.
* `finalOutput` — El resultado agregado de toda la ejecución.

Usa [Consultar estado de la ejecución](/es/reference/flowker/get-execution-status) para monitorear el progreso y [Consultar resultados de la ejecución](/es/reference/flowker/get-execution-results) para obtener la salida completa.

<Note>
  El endpoint principal de estado ([`GET /v1/executions/{id}`](/es/reference/flowker/get-execution-status)) devuelve `executionId`, `workflowId`, `status`, `currentStepNumber`, `totalSteps`, `startedAt`, `completedAt` y `errorMessage`. Los campos `stepResults` y `finalOutput` solo están disponibles a través del endpoint de resultados dedicado ([`GET /v1/executions/{id}/results`](/es/reference/flowker/get-execution-results)).
</Note>

## Idempotencia

***

Cada solicitud de ejecución requiere un header `Idempotency-Key`. Es un UUID que generas y envías con cada solicitud para identificarla de forma única.

Si Flowker recibe una segunda solicitud con el mismo `Idempotency-Key`, devuelve la respuesta original en lugar de crear una nueva ejecución. Esto hace que los reintentos sean seguros — las fallas de red y los timeouts no generarán ejecuciones duplicadas.

```
Idempotency-Key: 7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b
```

Usa siempre un UUID nuevo para cada ejecución. Reutiliza la misma clave solo al reintentar exactamente la misma solicitud.

## Dashboard

***

La API de Dashboard proporciona resúmenes agregados de tus workflows y ejecuciones — útil para construir dashboards operacionales y herramientas de monitoreo. Úsala siempre que necesites una visión de alto nivel de la salud del sistema sin consultar ejecuciones individuales.

* [Resumen de workflows](/es/reference/flowker/get-dashboard-workflow-summary) devuelve totales y desgloses por estado (draft, active, inactive).
* [Resumen de ejecuciones](/es/reference/flowker/get-dashboard-execution-summary) devuelve totales y desgloses por estado, con filtros opcionales de rango de tiempo y estado.

Ejemplo de respuesta de [`GET /v1/dashboards/executions`](/es/reference/flowker/get-dashboard-execution-summary):

```json theme={null}
{
  "total": 12847,
  "completed": 11903,
  "failed": 712,
  "pending": 130,
  "running": 102
}
```

Casos de uso comunes:

* **Monitorear la salud de las ejecuciones** — rastrea las tasas de completación y fallo a lo largo del tiempo para detectar degradaciones tempranamente.
* **Construir páginas de estado** — muestra métricas de throughput y éxito de los workflows en dashboards internos o dirigidos al cliente.
* **Alertar sobre picos en la tasa de fallos** — compara `failed / total` contra un umbral para disparar alertas antes de que los problemas se propaguen.

## Auditoría y cumplimiento

***

Flowker registra automáticamente una pista de auditoría inmutable para cada acción significativa — creación de workflows, cambios de estado, inicios y finalizaciones de ejecuciones, llamadas a executors y cambios de configuración. No necesitas habilitar ni configurar nada; el registro de auditoría ocurre internamente.

Propiedades clave del sistema de auditoría:

* **Inmutable** — los registros de auditoría son de solo adición y no pueden ser modificados ni eliminados.
* **Integridad mediante cadena de hashes** — cada entrada incluye un hash criptográfico que la vincula a la entrada anterior, haciendo detectable cualquier manipulación.
* **Búsqueda flexible** — usa [Buscar eventos de auditoría](/es/reference/flowker/search-audit-events) para consultar eventos por tipo, acción, resultado, recurso o rango de fechas.
* **Verificación de la cadena** — usa [Verificar cadena de hashes](/es/reference/flowker/verify-audit-hash-chain) para confirmar que la pista de auditoría no ha sido manipulada.

## Cómo encaja todo

***

Los conceptos de Flowker se construyen unos sobre otros en una secuencia clara:

1. **Explora el catálogo** para descubrir providers, executors, triggers y templates disponibles.
2. **Configura providers** para conectar Flowker a instancias activas de servicios externos.
3. **Configura executors** para definir las operaciones y endpoints específicos que tu workflow necesita.
4. **Define workflows** — desde cero o a partir de un template — referenciando tus configuraciones de executor.
5. **Ejecuta workflows** para correr tu proceso de negocio y obtener resultados.
6. **Monitorea y audita** — usa el dashboard para resúmenes operacionales y la API de auditoría para cumplimiento.

¿Listo para verlo en práctica? Sigue la [guía de primeros pasos](/es/flowker/flowker-getting-started) para ejecutar tu primer workflow de principio a fin.