Paso 1: Explorar el catálogo
El catálogo es un registro de solo lectura de los providers, executors del catálogo y triggers que vienen con Flowker. Los descubres; nunca los creas.
1
Listar providers disponibles
Llama al endpoint Listar providers del catálogo para ver los tipos de servicio a los que Flowker se conecta. El catálogo siempre incluye el conector HTTP genérico. Los proveedores nativos, como
ledger (Midaz) y tracer, se generan a partir de especificaciones OpenAPI publicadas y aparecen solo cuando el registro de esquemas nativos está configurado y la generación se completa correctamente.2
Listar executors del catálogo disponibles
Llama al endpoint Listar executors del catálogo para ver las operaciones que un node de workflow puede invocar. Usa Listar executors por provider para acotar la lista a un solo provider.
3
Listar triggers disponibles
Llama al endpoint Listar triggers del catálogo para ver los tipos de trigger integrados: webhooks y schedules. La API de ejecutar un workflow inicia un workflow, pero no es un trigger del catálogo.
Paso 2: Crear una configuración de provider
Llama a
POST /v1/provider-configurations para definir tu conexión a una instancia de un servicio externo.
Un
providerId es un identificador del catálogo, y no siempre coincide con el nombre del producto. Midaz está registrado como ledger. Toma siempre el valor de Listar providers del catálogo en lugar de deducirlo del nombre del producto.Ejemplo de solicitud
Ejemplo de solicitud
Autenticación
El bloqueconfig.auth contiene la autenticación que el servicio externo exige, como un par { type, config }. Usa el método que tu servicio espera.
Los campos secretos de
config.auth se almacenan fuera del documento de configuración persistido. Una lectura autorizada de la configuración del proveedor puede resolver esos valores desde el vault y devolverlos sin máscara; los campos que no se resuelven permanecen enmascarados. Otorga el acceso de lectura en consecuencia.
Cualquier otra cosa que pongas en el documento de configuración — un header, por ejemplo — se almacena junto con la configuración, y una lectura puede devolverla. Pon cada credencial en config.auth.
Para rotar un secreto, envía el nuevo valor en una actualización. Para conservar el actual, omite el campo o envíalo en blanco: esto funciona mientras auth.type no cambie. Una actualización que cambia auth.type debe llevar un valor para cada secreto que el nuevo tipo exige y el anterior no exigía; si falta, Flowker la rechaza con FLK-0952. Un cambio entre dos tipos que usan el mismo secreto, como de oidc_user a oidc_client_credentials, no necesita ese valor otra vez.
Ejemplo — OIDC client credentials
Ejemplo — OIDC client credentials
Habilitar y deshabilitar
Las configuraciones de provider tienen dos estados:active (en uso) y disabled (temporalmente offline). Se crean con estado active. Usa Deshabilitar configuración de provider para sacar una conexión de servicio y Habilitar configuración de provider para devolverla.
Consulta la API de Configuraciones de provider para la referencia completa.
Paso 3: Referenciar la configuración de provider desde un node de workflow
Cada node executor lleva un
providerConfigId — el identificador de la configuración de provider a través de la cual llama. Flowker rechaza un workflow cuyo node executor no tiene providerConfigId, y rechaza un valor que no sea un UUID. En tiempo de ejecución, 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.
Estos son los campos que un node executor define en su objeto data cuando llama a través del conector HTTP genérico:
Un node que llama a una operación de un documento OpenAPI subido la nombra con
operation_path y operation_method en lugar de un executorId. Flowker rellena el executorId por ti a partir de la configuración de provider a la que apunta el node. Conectar tu propia API recorre todo ese camino.
Validar la configuración de un node antes de guardarlo
Llama al endpoint Validar una configuración de node (POST /v1/catalog/executors/{id}/validate) para comprobar la configuración de un node contra el JSON Schema del executor del catálogo.
Esto ejecuta solo la validación de JSON Schema — verifica que tu objeto de configuración corresponde a la estructura que el executor del catálogo espera (campos obligatorios, tipos, formatos). No llama al servicio externo, así que la primera ida y vuelta real ocurre cuando un workflow ejecuta el node.
Pasa mappedTargets para nombrar los campos que tu node aporta mediante un inputMapping en lugar de un valor fijo. Esos campos cuentan como satisfechos, así que un node que mapea un campo obligatorio desde el trigger valida antes de guardarlo.
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 una forma 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.
Un target de entrada es una ruta en el cuerpo de la solicitud saliente, escrita exactamente como el servicio externo la espera: no hay objeto envoltorio ni prefijo que añadir. Un source de salida es una ruta dentro del envelope de respuesta, así que los campos de la respuesta quedan bajo body.
Ejemplo rápido — mapear campos del workflow a un node executor
Ejemplo rápido — mapear campos del workflow a un node executor
${executor-balance.balance}.Paso 4: Ejecutar el workflow
Referencia la configuración de provider en un node de workflow de tipo
executor.
El ejemplo a continuación crea un workflow de validación de pagos sobre la conexión FraudShield del Paso 2. Cuando llega un pago, Flowker llama al servicio 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 Actívalo y finalmente Ejecútalo.
Ejemplo — Crear un workflow de validación de pagos
Ejemplo — Crear un workflow de validación de pagos
check-fraud nombra http — el conector HTTP genérico del catálogo — y la configuración FraudShield creada en el Paso 2, que contiene la URL base y las credenciales. Ambos lados nombran el mismo provider, así que el workflow se guarda. Flowker envía la solicitud a https://api.fraudshield.example.com/score-transaction.El node no declara ningún outputMapping, así que su salida conserva la forma del envelope de respuesta. Por eso el score está en check-fraud.body.score, que es lo que lee la condición de evaluate-score. Añade un outputMapping cuando prefieras un nombre más plano — consulta Mapeo de campos y transformación de datos.Ejemplo — Ejecutar el workflow
Ejemplo — Ejecutar el workflow
Disparar workflows
Las ejecuciones de workflows se disparan a través del endpoint Ejecutar workflow:
inputData de la ejecución. Todos los campos están disponibles para los nodes siguientes 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.body.score para un node que no declara ningún outputMapping.
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, y reutiliza la misma clave solo cuando reintentes la solicitud idéntica.
Triggers de 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 un path de webhook en un workflow y los servicios externos envían solicitudes HTTP a ese path.
Cómo funciona
- Agrega un node trigger de tipo
webhooka tu workflow con unpath, unmethody uninput_contracten sudata. - Cuando el workflow se activa, Flowker registra el path en su registro de webhooks.
- Los sistemas externos envían solicitudes a
POST /v1/webhooks/{path}(o el método que configuraste). - Flowker resuelve el path al workflow correspondiente y lo ejecuta.
Definir un node trigger de webhook
El trigger de webhook es un node contype: "trigger" y triggerType: "webhook" en su data, más un path, un method y un input_contract. Configurar un trigger de webhook cubre cada campo, los tres modos de input_contract y lo que exige cada uno, y trae un node de ejemplo para cada modo.
La configuración del trigger es un contrato cerrado. Guardar un workflow cuyo trigger de webhook omite path, method o input_contract, olvida un campo que su modo input_contract exige, nombra el id de esquema o un campo de operación de otro modo, o lleva una clave o un valor que el esquema no acepta falla con FLK-0934. El esquema también declara los campos opcionales response_mode y response_view — consulta Modo de respuesta síncrona.
Proteger un webhook
La entrega de webhooks usa la misma autenticación que el resto de la API. Con Access Manager habilitado (PLUGIN_AUTH_ENABLED=true), cada solicitud a /v1/webhooks/* debe llevar un token Bearer (JWT OIDC), y quien llama debe tener el permiso execute sobre el recurso webhooks. Las solicitudes sin un token válido se rechazan con 401 Unauthorized.
Otorga ese permiso a una identidad máquina-a-máquina para cada sistema al que permitas llamar a tus webhooks, y gestiona la concesión en Access Manager. Esto mantiene el acceso a webhooks bajo el mismo modelo de roles y políticas que la gestión de workflows, en lugar de una credencial adjunta al path.
Metadatos del webhook
Flowker inyecta automáticamente un objeto_webhook en el inputData de la ejecución con metadatos sobre la solicitud entrante:
Estos metadatos están disponibles para todos los nodes del workflow a través del namespace
workflow._webhook.
Notas importantes
- Cada combinación de path + método de webhook solo puede ser registrada por un workflow activo. Activar un segundo workflow con el mismo path falla con un error de conflicto.
- Los paths de webhook admiten 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 arranca (el modo async) — quien llama 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 expire el límite interno de espera, Flowker recae en el mismo recibo
202 (con un header Location apuntando al endpoint de resultados) que habría devuelto el modo async.
response_view selecciona la forma del cuerpo de la respuesta sync:
El
finalOutput de una ejecución fallida (en las vistas full o final_output) lleva siempre status: "failed" y errorMessage, y errorClass cuando Flowker pudo clasificar el fallo — nunca un {} vacío. Sin un override responseStatusCode (ver abajo), el estado HTTP sync se mantiene en 200 para full/final_output/receipt (informa de la salud del transporte, no del resultado de negocio). Un responseStatusCode válido en el node set_output terminal sobrescribe ese estado para esas tres vistas.
Un node action 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 se aplica solo cuando el propio node set_output es el paso terminal — el estado retransmitido de un executor terminal siempre gana, y el fallback sin respuesta siempre usa un 200 simple para que un override nunca enmascare un fallo.
La detección de passthrough es estricta: solo cuenta el paso terminal. Un set_output terminal después de un executor toma la forma de su propia salida — Flowker nunca retrocede a la respuesta de un executor anterior. En una ejecución fallida, el paso que detiene el flujo es el paso terminal, así que un 4xx del provider que detuvo el workflow se retransmite como el 4xx real.
Los valores en la salida de un node set_output admiten referencias ${...} resueltas contra el contexto del workflow — incluyendo ${workflow.<campo>} (payload del trigger), ${execution.id}, ${execution.startedAt} y ${execution.now} (marcado en el momento de la interpolación). Una referencia ${...} que no se pueda resolver hace fallar el paso (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.
Los resultados de ejecución informan el status de la ejecución y stepResults. Un paso fallido proporciona stepNumber, nodeId, status y errorMessage, con statusCode y errorClass cuando están disponibles; output es opcional. No garantices un errorCode, incluidos FLK-0504 o FLK-0507, en cada payload de resultados de ejecución.
Reintentos y circuit breaker
Flowker incluye resiliencia integrada para las llamadas de executor.
Reintentos
Cuando una llamada de executor falla con un error transitorio — un error de red, un timeout en el intento, cualquier estado5xx, o los estados 408 o 429 — Flowker reintenta automáticamente. El comportamiento de reintento se configura por node, en el data del node 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. Un retry.max_attempts mayor que 1 activa los reintentos en ese node sea cual sea el método. Un retry.max_attempts de 1 no es una activación — define un solo intento.
Los errores no reintentables se reducen a un solo intento sin importar la configuración: circuit breaker abierto, contexto cancelado, errores de configuración, fallos al resolver secretos, un cuerpo de solicitud por encima del tope de tamaño configurado, un cuerpo de respuesta del provider por encima del mismo tope, y respuestas 4xx no transitorias del provider (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 saturados por llamadas fallidas repetidas:
Los errores
4xx de cliente/autenticación del provider no abren el circuito: son problema de quien llama, no una señal de que el provider esté caído. Solo los fallos de transporte y los 5xx cuentan para el umbral.
Cuando el circuito está abierto, las llamadas de executor fallan de inmediato con FLK-0507 en lugar de alcanzar el servicio externo. Esto evita fallos en cascada y da tiempo al servicio externo para recuperarse.
Transiciones de estado del circuit breaker
Registro de configuraciones de executor
Flowker mantiene un registro de configuraciones de executor. El registro expone cuatro operaciones:
Cada registro lleva un
status, que la API informa en cada respuesta:
PATCH acepta name, baseUrl, endpoints y authentication, más los opcionales description y metadata. No acepta status, pero la operación de listado acepta status 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.
Qué sigue
Conceptos fundamentales
Comprende workflows, nodes, edges y ejecuciones.
API de Configuraciones de provider
Explora la API de configuraciones de provider.