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

> Entiende los bloques de construcción de Flowker: workflows, nodos, aristas, catálogo, configuraciones de proveedor, plantillas, ejecuciones y dashboard.

Flowker se basa en un conjunto de conceptos interconectados. La última sección de esta página muestra cómo se conecta todo.

## Workflows

***

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

Los workflows pasan por un ciclo de vida:

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

Para mover un workflow entre estados, usa los endpoints [activate](/es/reference/products/flowker/activate-workflow), [deactivate](/es/reference/products/flowker/deactivate-workflow) y [move to draft](/es/reference/products/flowker/move-workflow-to-draft).

## Nodos y aristas

***

Los nodos son los pasos individuales de un workflow, o **tareas** en términos de negocio. Cada nodo es una unidad de trabajo: recibir un evento, llamar a un servicio, evaluar una condición o hacer una acción.

Flowker admite cuatro tipos de nodo:

| Tipo          | Propósito                                                                                                 | Cuándo usarlo                                                        |
| ------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `trigger`     | Punto de entrada del workflow                                                                             | Siempre el primer nodo. Inicia la ejecución cuando ocurre un evento. |
| `executor`    | Llama a un servicio externo a través de una configuración de proveedor                                    | Cuando necesitas llamar a una API o integración externa.             |
| `conditional` | Ramifica la ejecución según condiciones                                                                   | Cuando el paso siguiente depende del resultado de uno anterior.      |
| `action`      | Hace una acción integrada; el tipo disponible es `set_output`, que define la salida final de la ejecución | Para definir la salida final del workflow sin una llamada externa.   |

Las **aristas** conectan los nodos y definen el orden de ejecución. La ramificación vive en el nodo condicional, no en la arista: el nodo condicional evalúa su condición y produce un handle de resultado, y Flowker sigue la única arista saliente cuyo `sourceHandle` coincide con ese handle. Todos los demás tipos de nodo siguen todas sus aristas salientes.

## Catálogo

***

El catálogo es el registro de solo lectura de todos los proveedores, ejecutores y disparadores integrados disponibles en Flowker. No puedes crear ni modificar entradas del catálogo. Las descubres.

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

* **Los ejecutores del catálogo** son los componentes integrados que invoca un nodo de workflow. Incluyen el conector HTTP genérico y las operaciones de proveedores nativos como el ledger de Midaz y Tracer.
* **Los disparadores** definen los tipos de evento que pueden iniciar un workflow (por ejemplo, webhooks).

Usa estos endpoints para explorar lo que hay disponible:

* [List catalog executors](/es/reference/products/flowker/list-catalog-executors) y [List catalog triggers](/es/reference/products/flowker/list-catalog-triggers) para descubrir los tipos de ejecutor y de disparador.
* [List catalog providers](/es/reference/products/flowker/list-catalog-providers) (`GET /v1/catalog/providers`) para listar todos los proveedores disponibles.
* [Get catalog provider](/es/reference/products/flowker/get-catalog-provider) (`GET /v1/catalog/providers/{id}`) para obtener los detalles de un proveedor específico.
* [List executors by provider](/es/reference/products/flowker/list-executors-by-provider) (`GET /v1/catalog/providers/{id}/executors`) para listar los ejecutores disponibles de un proveedor específico.

## Configuraciones de proveedor

***

Una **configuración de proveedor** es tu conexión a una instancia activa de un servicio externo. Es el objeto al que apunta un nodo de workflow, y el objeto que Flowker lee cuando ese nodo corre.

Flowker separa el tipo de servicio de tu conexión a él:

| Concepto                       | Qué es                                                                               | Naturaleza                            |
| ------------------------------ | ------------------------------------------------------------------------------------ | ------------------------------------- |
| **Proveedor**                  | Un tipo de servicio externo (por ejemplo, Midaz, Tracer, un endpoint HTTP genérico). | Estático — publicado en el catálogo.  |
| **Configuración de proveedor** | Tu conexión a una instancia de ese proveedor.                                        | Dinámico — las creas y las gestionas. |

Cada configuración de proveedor contiene:

* **`config`**: los detalles de conexión de esa instancia, como la URL base y las credenciales de autenticación. Para la clase `catalog` predeterminada, Flowker valida este mapa contra el JSON Schema del proveedor del catálogo. Para `external_openapi`, usa un validador de configuración de OpenAPI externo. Las hojas sensibles reconocidas 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 a los que esta configuración puede llamar.
* **`allowedPrivateHosts`**: hosts privados con nombre que tu equipo de operaciones permite alcanzar a esta configuración. Levanta solo la restricción de Flowker sobre direcciones privadas o de loopback: si `allowedHosts` no está vacío, también debe incluir el host. Los metadatos de nube y las direcciones link-local siguen bloqueados.
* **`schemaBindings`**: los esquemas XSD u OpenAPI vinculados a esta configuración, cada uno con una restricción opcional a operaciones específicas de OpenAPI.

Una configuración también lleva un **`kind`**. Los valores admitidos son `catalog` (el predeterminado), que conecta con un proveedor del catálogo, y `external_openapi`, que conecta con un documento OpenAPI que subiste tú mismo para que un nodo de workflow llame a las operaciones de tu propia API. Consulta [Conectar tu propia API](/es/products/flowker/connecting-your-own-api).

Las configuraciones de proveedor tienen dos estados: `active` (en uso) y `disabled` (fuera de línea de forma temporal). Usa [Disable provider configuration](/es/reference/products/flowker/disable-provider-configuration) para sacar una conexión de servicio y [Enable provider configuration](/es/reference/products/flowker/enable-provider-configuration) para devolverla.

### Cómo un workflow llega a ella

Cada nodo ejecutor puede llevar un `providerConfigId`, el identificador de la configuración de proveedor 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 proveedor más la ruta del nodo, y el nodo falla si la configuración de proveedor no está en `active`.

Usa los endpoints de [Provider configurations](/es/reference/products/flowker/list-provider-configurations) para crear, leer, actualizar, deshabilitar, habilitar y eliminar tus conexiones.

## Registro de configuraciones de ejecutor

***

Flowker mantiene un registro de entradas de configuración de ejecutor. El registro expone cuatro operaciones:

| Operación  | Endpoint                                                                                    |
| ---------- | ------------------------------------------------------------------------------------------- |
| Listar     | [`GET /v1/executors`](/es/reference/products/flowker/list-executor-configurations)          |
| Obtener    | [`GET /v1/executors/{id}`](/es/reference/products/flowker/get-executor-configuration)       |
| Actualizar | [`PATCH /v1/executors/{id}`](/es/reference/products/flowker/update-executor-configuration)  |
| Eliminar   | [`DELETE /v1/executors/{id}`](/es/reference/products/flowker/delete-executor-configuration) |

Cada entrada lleva un `status`, que la API reporta en cada respuesta:

| Estado         | Descripción                                       |
| -------------- | ------------------------------------------------- |
| `unconfigured` | La entrada todavía no tiene detalles de conexión. |
| `configured`   | La entrada lleva detalles de conexión.            |
| `tested`       | La entrada se verificó.                           |
| `active`       | La entrada está en servicio.                      |
| `disabled`     | La entrada está fuera de servicio.                |

El cuerpo de la actualización no incluye `status`, pero la operación de listado lo acepta como filtro de consulta. La actualización aplica a las entradas con estado `unconfigured` o `configured`. La eliminación aplica a las entradas con estado `unconfigured`, `configured` o `disabled`. Ninguna operación de esta versión mueve una entrada a `tested`, `active` o `disabled`. La tabla lista esos valores porque las respuestas los reportan y el filtro de listado los acepta.

## Plantillas

***

Las plantillas de workflow son patrones de workflow prediseñados publicados en el catálogo. Cada plantilla describe un patrón de integración conocido y los parámetros que ese patrón espera.

El catálogo incluye la plantilla `tracer-midaz-validation` ("Tracer Validation + Midaz Transaction"): recibe una solicitud de webhook, valida la transacción a través de Tracer y crea la transacción en Midaz cuando Tracer la aprueba.

Cada plantilla tiene un esquema de parámetros que define qué entradas espera (por ejemplo, qué configuración de proveedor usar, valores de umbral). Cuando Flowker puede recuperar configuraciones de proveedor activas, enriquece los campos de parámetro referenciados con opciones seleccionables. Si la búsqueda no está disponible o falla, devuelve el esquema original.

Para inspeccionar una plantilla:

1. [Lista las plantillas del catálogo](/es/reference/products/flowker/list-catalog-templates).
2. [Obtén el detalle de la plantilla](/es/reference/products/flowker/get-catalog-template) para ver su esquema de parámetros.
3. [Valida un conjunto de parámetros](/es/reference/products/flowker/validate-catalog-template-params) contra ese esquema.

## Ejecuciones

***

Una ejecución es una instancia en tiempo de ejecución de un workflow. Un disparador 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 nodo ejecutor, condicional o de acción ejecutado, en orden. Los nodos disparadores inician el recorrido del grafo y no crean registros de paso de ejecución.
* `finalOutput`: el valor final que se persiste para la ejecución. Cuando una acción `set_output` produce un objeto, Flowker usa ese objeto. De lo contrario, Flowker devuelve el contexto acumulado del workflow.

Usa [Get execution status](/es/reference/products/flowker/get-execution-status) para monitorear el progreso y [Get execution results](/es/reference/products/flowker/get-execution-results) para recuperar la salida completa.

<Note>
  El endpoint de estado devuelve el registro de la ejecución, incluido su estado actual. El endpoint dedicado de resultados ([`GET /v1/executions/{id}/results`](/es/reference/products/flowker/get-execution-results)) devuelve `status`, `stepResults` y `finalOutput` cuando están presentes. Un paso fallido puede incluir `errorMessage`. Esta respuesta no tiene un campo de detalles de error en el nivel superior.
</Note>

## Idempotencia

***

Las solicitudes de ejecución directa requieren una cadena `Idempotency-Key` no vacía. Flowker no exige el formato UUID. El header del 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 intencionalmente una nueva ejecución. Reutiliza la misma clave solo cuando reintentes exactamente la misma solicitud.

## Dashboard

***

La API del Dashboard provee resúmenes agregados de tus workflows y ejecuciones. Úsala cuando necesites una vista de alto nivel de la salud del sistema sin consultar ejecuciones individuales.

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

Respuesta de ejemplo de [`GET /v1/dashboards/executions`](/es/reference/products/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 finalización y de fallo a lo largo del tiempo para detectar la degradación temprano.
* **Construir páginas de estado**: muestra el throughput de los workflows y las métricas de éxito en dashboards internos o de cara 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 los proveedores, ejecutores del catálogo, disparadores y plantillas disponibles.
2. **Crea configuraciones de proveedor** para conectar Flowker con instancias activas de servicios externos.
3. **Define workflows**: cada nodo ejecutor nombra un ejecutor del catálogo y la configuración de proveedor a través de la cual llama.
4. **Ejecuta workflows** para correr tu proceso de negocio y recuperar los resultados.
5. **Monitorea**: usa el dashboard para los resúmenes operativos y la API de ejecuciones para el detalle por paso.

Sigue la [guía de primeros pasos](/es/products/flowker/flowker-getting-started) para ejecutar tu primer workflow de extremo a extremo.