Ciclo de vida de la configuración de executor
Antes de que un executor pueda ser usado en un workflow, pasa por el siguiente ciclo de vida:
Ciclo de vida de la configuración de executor
/v1/executors (listar, obtener, actualizar, eliminar). Los estados del ciclo de vida (unconfigured, configured, tested, active, disabled) se rastrean internamente — las transiciones ocurren a través de la capa de servicio.
El ciclo de vida de la configuración de executor se gestiona a través de la capa de servicio (comandos
MarkConfigured, MarkTested, Activate, Disable, Enable). Ten en cuenta que la API HTTP actual expone los endpoints GET, PATCH y DELETE. PATCH actualiza los datos de configuración pero no dispara transiciones de estado.Paso 1: Explorar el catálogo
Antes de crear una configuración de executor, explora el catálogo para ver qué está disponible. El catálogo es un registro de solo lectura de executors y triggers integrados que vienen con Flowker. No necesitas crear entradas en el catálogo — las descubres y luego configuras las que necesitas.
1
Listar executors disponibles
Llama al endpoint Listar executors del catálogo para ver todos los tipos de executor que Flowker soporta — solicitudes HTTP, transformaciones de datos y más.
2
Listar triggers disponibles
Llama al endpoint Listar triggers del catálogo para ver cómo se pueden iniciar los workflows — webhooks o llamadas API manuales.
3
Elige lo que necesitas
Identifica el tipo de executor y trigger que coincidan con tu integración. Los referenciarás al crear tu configuración en el siguiente paso.
Paso 2: Configurar una conexión de provider y el executor
Los executors son componentes integrados que vienen con Flowker. No se crean a través de la API — se descubren a través del catálogo (
GET /v1/catalog/executors) en el Paso 1.
Para usar un executor, primero creas una configuración de provider que define la conexión al servicio externo, y luego gestionas las configuraciones de executor que vinculan un executor del catálogo a una conexión de provider con ajustes específicos de la operación.
Crear una configuración de provider
Llama aPOST /v1/provider-configurations para establecer la conexión a tu servicio externo — incluyendo la URL base, credenciales y configuraciones específicas del entorno. El campo config se valida contra el JSON Schema del provider desde el catálogo.
Consulta Configuraciones de provider más abajo para ver detalles y ejemplos.
Gestionar configuraciones de executor
Una vez que tienes una configuración de provider, gestiona las configuraciones de executor a través de los endpoints/v1/executors:
Una configuración de executor define qué endpoint llamar y cómo mapear los datos para esa operación. Referencia una configuración de provider para los detalles reales de conexión.
Consulta la API de configuraciones de executor para la referencia completa.
Tipos de autenticación
Flowker soporta múltiples métodos de autenticación. Usa el método requerido por tu servicio externo.
Ejemplo — OIDC client credentials
Ejemplo — OIDC client credentials
Configuraciones de provider
Las configuraciones de provider son independientes de las configuraciones de executor. Mientras una configuración de executor define cómo Flowker llama a una operación específica en un servicio externo, una configuración de provider representa una conexión configurada a una instancia de provider — incluyendo su URL base, credenciales y configuraciones específicas del entorno. Piénsalo así: una configuración de provider es la conexión, y una configuración de executor es la operación que ejecutas sobre esa conexión.
Crear una configuración de provider
Crea una configuración de provider llamando al endpoint Crear configuración de provider. Proporciona elproviderId del catálogo y la configuración específica del provider (URL base, credenciales, etc.).
El campo config se valida contra el JSON Schema del provider en el catálogo. Si no coincide, la solicitud devuelve un error 422.
Ejemplo de solicitud
Ejemplo de solicitud
Probar conectividad
Después de crear una configuración de provider, pruébala con el endpoint Probar configuración de provider. La prueba ejecuta tres etapas — conectividad, autenticación y de extremo a extremo — y devuelve resultados para cada una.Habilitar y deshabilitar
Las configuraciones de provider se crean con estadoactive. Puedes deshabilitar temporalmente una con el endpoint Deshabilitar configuración de provider y rehabilitarla después con el endpoint Habilitar configuración de provider.
Consulta la API de configuraciones de provider para la referencia completa.
Paso 3: Configurar el executor
Marca el executor como configurado llamando al endpoint Update executor configuration. Esto transiciona el estado de
unconfigured a configured.
Paso 4: Valida tu configuración
Antes de usar un executor en un workflow, valida su configuración contra el schema del catálogo usando el endpoint Validate executor config (
POST /v1/catalog/executors/{id}/validate).
Esto ejecuta solo validación de JSON Schema — verifica que tu objeto de configuración coincida con la estructura que espera el executor (campos requeridos, tipos, formatos). No prueba conectividad con el servicio externo.
Para probar la conectividad real con un servicio externo, usa el endpoint Probar configuración de provider sobre la configuración de provider en su lugar. Ese endpoint ejecuta verificaciones de conectividad, autenticación y de extremo a extremo contra el servicio real.
Mapeo de campos y transformación de datos
Cuando los datos del workflow no coinciden con el formato que espera un servicio externo — o cuando un servicio devuelve datos en un formato que el siguiente paso no puede consumir — usa mapeos de campos y transformaciones para cubrir esa brecha. Los mapeos de campos y transformaciones se definen dentro del objeto
data de los nodes executor. Flowker aplica los mapeos de entrada antes de llamar al servicio externo, y los mapeos de salida después de recibir la respuesta.
Ejemplo rápido — mapear campos del workflow a un executor
Ejemplo rápido — mapear campos del workflow a un executor
Paso 5: Usar el executor en un workflow
Una vez que tu configuración de executor está validada, referénciala en un workflow. El executor se vuelve activo cuando se usa en un workflow activo. Para sacar temporalmente un executor de servicio, actualiza su configuración usando el endpoint Update executor configuration.
Usar un executor en un workflow
Referencia el executor en un node de tipo
executor.
El ejemplo a continuación crea un workflow de validación de pagos. Cuando llega un pago, Flowker llama al executor de verificación de fraude, evalúa el score de riesgo y aprueba o rechaza el pago según el resultado.
El workflow tiene cinco nodes: un trigger webhook que recibe el pago, un node executor que llama al servicio de verificación de fraude, un node conditional que evalúa el score, y dos nodes action para los resultados de aprobación y rechazo. Los edges los conectan en secuencia, con el node condicional bifurcando hacia uno u otro camino según el umbral del score.
Usa el endpoint Crear workflow para definir el workflow, luego Activar, y finalmente Ejecutar.
Ejemplo — Crear un workflow de validación de pagos
Ejemplo — Crear un workflow de validación de pagos
Ejemplo — Ejecutar el workflow
Ejemplo — Ejecutar el workflow
Disparar workflows
Las ejecuciones de workflows se disparan a través del endpoint Ejecutar workflow:
inputData para la ejecución. Todos los campos están disponibles para los nodes subsiguientes a través del namespace workflow — por ejemplo, workflow.transactionId o workflow.amount. Las salidas de los nodes están disponibles a través del ID del node — por ejemplo, check-fraud.score.
Idempotencia
Cada solicitud de ejecución debe incluir un headerIdempotency-Key. Las solicitudes sin él se rechazan con 400 Bad Request (error FLK-0509). Genera un UUID nuevo para cada ejecución nueva y reutiliza la misma clave solo cuando reintentes la solicitud idéntica.
Triggers por webhook
Los webhooks son la forma principal en que los sistemas externos disparan workflows de Flowker. En lugar de que tu sistema llame directamente a la API de ejecuciones, registras una ruta de webhook en un workflow y los servicios externos envían solicitudes HTTP a esa ruta.
Cómo funciona
- Agrega un node trigger de tipo
webhooka tu workflow con unpathymethoden sudata. - Cuando el workflow se activa, Flowker registra la ruta en su registro de webhooks.
- Los sistemas externos envían solicitudes a
POST /v1/webhooks/{path}(o el método que configuraste). - Flowker resuelve la ruta hacia el workflow correspondiente y lo ejecuta.
Definir un node trigger de webhook
El trigger de webhook es un node contype: "trigger" y los siguientes campos en data:
Ejemplo — Node trigger de webhook
Ejemplo — Node trigger de webhook
Metadata del webhook
Flowker inyecta automáticamente un objeto_webhook en el inputData de la ejecución con metadata sobre la solicitud entrante:
Este metadata está disponible para todos los nodes del workflow a través del namespace
workflow._webhook.
Notas importantes
- Cada combinación de ruta de webhook + método solo puede ser registrada por un workflow activo. Activar un segundo workflow con la misma ruta falla con un error de conflicto.
- Las rutas de webhook soportan segmentos anidados (p. ej.,
payments/stripe/received). - El tamaño máximo del cuerpo de la solicitud es 1 MB.
- Desactivar un workflow desregistra automáticamente sus rutas de webhook.
Modo de respuesta síncrona
Por defecto, un trigger de webhook responde con un recibo202 en cuanto la ejecución inicia (el modo asíncrono) — el llamador debe consultar el estado de la ejecución por separado. Define response_mode como "sync" en el data del node trigger para que Flowker mantenga la conexión HTTP abierta y devuelva el resultado de la ejecución directamente en la respuesta:
Si la ejecución no alcanza un estado terminal antes de que se agote el límite interno de espera, Flowker recurre al mismo recibo
202 (con un header Location que apunta al endpoint de resultados) que habría devuelto el modo asíncrono.
response_view define la forma del cuerpo de la respuesta síncrona:
El
finalOutput de una ejecución fallida (en la vista full o final_output) siempre incluye status: "failed" y errorMessage, y errorClass cuando Flowker pudo clasificar el fallo — nunca un {} vacío. Sin un override de responseStatusCode (ver abajo), el estado HTTP síncrono se mantiene en 200 para full/final_output/receipt (reporta salud del transporte, no el resultado de negocio). Un responseStatusCode válido en el node set_output terminal sobrescribe ese estado para esas tres vistas.
Un node de acción con actionType: "set_output" puede llevar un responseStatusCode opcional (entero, 200–599) para sobrescribir el estado HTTP que devuelve una respuesta de webhook sync. Un valor fuera de rango o no entero se rechaza al guardar (FLK-0122). Para passthrough, el override aplica solo cuando el propio node set_output es el step terminal — el estado reenviado de un executor terminal siempre gana, y el fallback sin respuesta siempre usa un 200 plano para que un override nunca enmascare un fallo.
La detección de passthrough es estricta: solo cuenta el step terminal. Un set_output terminal después de un executor se responde con su propio output — Flowker nunca retrocede a la respuesta de un executor anterior. En una ejecución fallida el step que detuvo la ejecución es el terminal, así que un 4xx del proveedor que detuvo el workflow se reenvía como el 4xx real.
Los valores del output de un node set_output soportan referencias ${...} resueltas contra el contexto del workflow — incluyendo ${workflow.<campo>} (payload del trigger), ${execution.id}, ${execution.startedAt} y ${execution.now} (sellado en el momento de la interpolación). Una referencia ${...} que no se puede resolver hace fallar el step (fail-closed).
Manejo de errores
Si un node falla, la ejecución se detiene y se marca como
failed.
No hay fallback automático. Después de agotar los reintentos, la ejecución falla.
Cada falla incluye:
- Node fallido y razón
- Número de paso y salida
- Código de error
Reintentos y circuit breaker
Flowker incluye resiliencia integrada para llamadas a executors.
Reintentos
Cuando una llamada a un executor falla con un error transitorio, Flowker reintenta automáticamente. El comportamiento de reintento es configurable por node en la configuración del executor:
Los reintentos solo aplican cuando la operación es segura de repetir. Por defecto, las llamadas
POST y PATCH se tratan como no idempotentes y no se reintentan (un solo intento), mientras que GET, PUT, DELETE y otros verbos reintentan normalmente. Configurar retry.max_attempts explícitamente en un node habilita los reintentos para ese node sin importar el método.
Errores no reintentables cortan a un solo intento sin importar la configuración: circuit breaker abierto, contexto cancelado, errores de configuración, fallos de resolución de secretos y respuestas 4xx no transitorias del proveedor (cualquier 4xx excepto 408 y 429).
El reintento aplica por ejecución de node. Si todos los intentos fallan, el paso se marca como fallido y la ejecución se detiene.
Circuit breaker
Flowker usa un circuit breaker para proteger a los servicios externos de ser abrumados por llamadas fallidas repetidas:
Los errores
4xx de cliente/autenticación del proveedor no disparan el circuito: son un problema del llamador, no una señal de que el proveedor está caído. Solo las fallas de transporte y 5xx cuentan para el umbral.
Cuando el circuito está abierto, las llamadas a executors fallan inmediatamente con FLK-0507 en lugar de llegar al servicio externo. Esto previene fallas en cascada y da tiempo al servicio externo para recuperarse.
Transiciones de estado del circuit breaker
Próximos pasos
Conceptos fundamentales
Comprende workflows, nodes, edges y ejecuciones.
Executor configurations API
Explora la API de configuración de executors.

