> ## 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, nodes, edges, catálogo, configuraciones de provider, templates, ejecuciones y dashboard. 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. La última sección 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 a través de una configuración de provider | 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; el tipo disponible es `set_output`, que define el output final de la ejecución | Para definir el output final del workflow sin una llamada externa. | Los **edges** conectan nodes y definen el orden de ejecución. La bifurcación vive en el node conditional, no en el edge: el node conditional evalúa su condición y produce un handle de resultado, y Flowker sigue el único edge saliente cuyo `sourceHandle` coincide con ese handle. Todos los demás tipos de node siguen todos sus edges salientes. ## 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 del catálogo** son los componentes integrados que un node invoca — el conector HTTP genérico y las operaciones de providers nativos como el ledger de Midaz y Tracer. Los descubres; nunca los creas. * 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 de provider *** Una **configuración de provider** es tu conexión a una instancia activa de un servicio externo. Es el objeto al que apunta un node y el objeto que Flowker lee cuando ese node se ejecuta. Flowker separa el tipo de servicio de tu conexión a él: | Concepto | Qué es | Naturaleza | | ----------------------------- | ------------------------------------------------------------------------------- | ------------------------------------ | | **Provider** | Un tipo de servicio externo (p. ej., Midaz, Tracer, un endpoint HTTP genérico). | Estático — publicado en el catálogo. | | **Configuración de provider** | Tu conexión a una instancia de ese provider. | Dinámica — tú la creas y gestionas. | Cada configuración de provider contiene: * **`config`** — los detalles de conexión de esa instancia, como la URL base y las credenciales de autenticación. Para el kind predeterminado `catalog`, Flowker valida este mapa contra el JSON Schema del provider del catálogo. Para `external_openapi`, usa un validador de configuración de OpenAPI externa. Los campos sensibles reconocidos se escriben en el backend de secretos y se reemplazan por `secretRef`; las configuraciones heredadas sin `secretRef` pueden contener valores en línea. * **`allowedHosts`** — los hosts públicos que esta configuración puede llamar. * **`allowedPrivateHosts`** — hosts privados nombrados que tu equipo de operaciones permite alcanzar a esta configuración. Solo levanta la restricción de Flowker para direcciones privadas o loopback: si `allowedHosts` no está vacío, también debe incluir el host. Las direcciones de metadatos de nube y link-local siguen bloqueadas. * **`schemaBindings`** — los esquemas XSD u OpenAPI vinculados a esta configuración, cada uno con una restricción opcional a operaciones OpenAPI específicas. Una configuración también lleva un **`kind`**. Los valores admitidos son `catalog` (el valor por defecto), que conecta a un provider del catálogo, y `external_openapi`, que conecta a un documento OpenAPI que subiste tú para que un node de workflow llame a las operaciones de tu propia API — consulta [Conectar tu propia API](/es/flowker/connecting-your-own-api). Las configuraciones de provider tienen dos estados: `active` (en uso) y `disabled` (temporalmente offline). Usa [Deshabilitar configuración de provider](/es/reference/flowker/disable-provider-configuration) para sacar una conexión de servicio y [Habilitar configuración de provider](/es/reference/flowker/enable-provider-configuration) para devolverla. ### Cómo un workflow la alcanza Cada node executor puede llevar un `providerConfigId` — el identificador de la configuración de provider a través de la cual llama. En tiempo de ejecución, Flowker construye cada solicitud saliente con la URL base de esa configuración de provider más el path del node, y el node falla si la configuración de provider no está `active`. Usa los endpoints de [Configuraciones de provider](/es/reference/flowker/list-provider-configurations) para crear, leer, actualizar, deshabilitar, habilitar y eliminar tus conexiones. ## Registro de configuraciones de executor *** Flowker mantiene un registro de configuraciones de executor. El registro expone cuatro operaciones: | Operación | Endpoint | | ---------- | ---------------------------------------------------------------------------------- | | Listar | [`GET /v1/executors`](/es/reference/flowker/list-executor-configurations) | | Obtener | [`GET /v1/executors/{id}`](/es/reference/flowker/get-executor-configuration) | | Actualizar | [`PATCH /v1/executors/{id}`](/es/reference/flowker/update-executor-configuration) | | Eliminar | [`DELETE /v1/executors/{id}`](/es/reference/flowker/delete-executor-configuration) | Cada registro lleva un `status`, que la API informa en cada respuesta: | Estado | Descripción | | -------------- | ---------------------------------------------- | | `unconfigured` | El registro aún no tiene detalles de conexión. | | `configured` | El registro lleva detalles de conexión. | | `tested` | El registro fue verificado. | | `active` | El registro está en servicio. | | `disabled` | El registro está fuera de servicio. | El cuerpo de actualización no incluye `status`, pero la operación de listado lo acepta como filtro de consulta. La actualización aplica a registros en estado `unconfigured` o `configured`; la eliminación aplica a registros en estado `unconfigured`, `configured` o `disabled`. Ninguna operación en esta versión mueve un registro a `tested`, `active` o `disabled`; la tabla lista esos valores porque las respuestas los informan y el filtro de listado los acepta. ## Templates *** Los templates de workflow son patrones pre-construidos publicados en el catálogo. Cada template describe un patrón de integración conocido y los parámetros que ese patrón espera. El catálogo trae el template `tracer-midaz-validation` ("Tracer Validation + Midaz Transaction"): recibe una solicitud de webhook, valida la transacción con Tracer y crea la transacción en Midaz cuando Tracer la aprueba. 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 Flowker puede recuperar configuraciones de provider activas, enriquece los campos de parámetros referenciados con opciones seleccionables. Si la consulta no está disponible o falla, devuelve el schema original. Para inspeccionar un template: 1. [Lista los templates del catálogo](/es/reference/flowker/list-catalog-templates). 2. [Consulta el detalle del template](/es/reference/flowker/get-catalog-template) para ver su schema de parámetros. 3. [Valida un conjunto de parámetros](/es/reference/flowker/validate-catalog-template-params) contra ese schema. ## Ejecuciones *** Una ejecución es una instancia en tiempo de ejecución de un workflow. Una activación normalmente inicia una nueva ejecución; un reintento que reutiliza una clave de idempotencia existente devuelve la ejecución preexistente en lugar de crear otra. 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 executor, condicional o de acción ejecutado, en orden. Los nodes trigger inician el recorrido del grafo y no crean registros de pasos de ejecución. * `finalOutput` — El valor final persistido para la ejecución. Cuando una acción `set_output` produce un objeto, Flowker usa ese objeto; de lo contrario, devuelve el contexto acumulado del workflow. 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. El endpoint de estado devuelve el registro de la ejecución, incluido su estado actual. El endpoint de resultados dedicado ([`GET /v1/executions/{id}/results`](/es/reference/flowker/get-execution-results)) devuelve `status`, `stepResults` y `finalOutput` cuando está presente. Un paso fallido puede incluir `errorMessage`; esta respuesta no tiene un campo de detalles de error de nivel superior. ## Idempotencia *** Las solicitudes directas de ejecución requieren una cadena `Idempotency-Key` no vacía; Flowker no exige formato UUID. El header de webhook es opcional. Si Flowker recibe una segunda solicitud con el mismo `Idempotency-Key`, devuelve la ejecución preexistente en lugar de crear otra. Una repetición directa devuelve HTTP `200` e incluye `idempotencyReplayed` en la respuesta. ``` Idempotency-Key: 7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b ``` Usa una clave nueva cuando quieras crear una ejecución nueva de forma intencional. 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. ## 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 del catálogo, triggers y templates disponibles. 2. **Crea configuraciones de provider** para conectar Flowker a instancias activas de servicios externos. 3. **Define workflows** — cada node executor nombra un executor del catálogo y la configuración de provider a través de la cual llama. 4. **Ejecuta workflows** para correr tu proceso de negocio y obtener resultados. 5. **Monitorea** — usa el dashboard para resúmenes operacionales y la API de ejecuciones para el detalle por paso. ¿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.