Paso 1: Explora el catálogo
El catálogo es un registro de solo lectura de los proveedores, los ejecutores del catálogo y los disparadores que vienen con Flowker. Los descubres. Nunca los creas.
1
Lista los proveedores disponibles
Llama al endpoint Listar proveedores del catálogo para ver los tipos de servicio a los que se conecta Flowker. El catálogo siempre incluye el conector HTTP genérico. Los proveedores nativos como
ledger (Midaz) y tracer se sintetizan a partir de especificaciones de OpenAPI publicadas y aparecen solo cuando el registro de esquemas nativos está configurado y la síntesis tiene éxito.2
Lista los ejecutores del catálogo disponibles
Llama al endpoint Listar ejecutores del catálogo para ver las operaciones que un nodo de workflow puede invocar. Usa Listar ejecutores por proveedor para acotar la lista a un proveedor.
3
Lista los disparadores disponibles
Llama al endpoint Listar disparadores del catálogo para ver los tipos de disparador integrados: webhooks y programaciones. La API de ejecución de workflow inicia un workflow pero no es un disparador del catálogo.
Paso 2: Crea una configuración de proveedor
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. El catálogo registra Midaz como ledger. Toma siempre el valor de Listar proveedores del catálogo en lugar de adivinarlo a partir del nombre del producto.Solicitud de ejemplo
Solicitud de ejemplo
Autenticación
El bloqueconfig.auth contiene la autenticación que requiere el servicio externo, como un par { type, config }. Usa el método que espera tu servicio.
Flowker almacena las hojas secretas de
config.auth fuera del documento de configuración persistido. Una lectura autorizada de la configuración de proveedor puede resolver esos valores desde el vault y devolverlos en claro. Las hojas sin resolver permanecen enmascaradas. Otorga el acceso de lectura en consecuencia.
Cualquier otra cosa que coloques en el documento de configuración (un header, por ejemplo) permanece con la configuración, y una lectura puede devolverla. Coloca 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 vacío. Esto funciona mientras auth.type siga siendo el mismo. Una actualización que cambia auth.type debe llevar un valor para cada secreto que el nuevo tipo requiere y el anterior no. De lo contrario 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 de nuevo.
Ejemplo: client credentials de OIDC
Ejemplo: client credentials de OIDC
Habilitar y deshabilitar
Las configuraciones de proveedor tienen dos estados:active (en uso) y disabled (temporalmente fuera de línea). Una nueva configuración de proveedor empieza en estado active. Usa Deshabilitar una configuración de proveedor para sacar una conexión de servicio y Habilitar una configuración de proveedor para devolverla.
Consulta la API de configuraciones de proveedor para la referencia completa.
Paso 3: Referencia la configuración de proveedor desde un nodo de workflow
Cada nodo ejecutor lleva un
providerConfigId, el identificador de la configuración de proveedor a través de la cual llama. Flowker rechaza un workflow cuyo nodo ejecutor no tiene providerConfigId, y rechaza un valor que no es un UUID. En tiempo de ejecución construye cada solicitud saliente a partir de la URL base de esa configuración de proveedor más el path del nodo. El nodo falla si la configuración de proveedor no está active.
Estos son los campos que un nodo ejecutor establece en su objeto data cuando llama a través del conector HTTP genérico:
Un nodo que llama a una operación de un documento de OpenAPI subido la nombra con
operation_path y operation_method en lugar de un executorId. Flowker completa el executorId por ti a partir de la configuración de proveedor a la que apunta el nodo. Conectar tu propia API recorre todo ese camino.
Valida la configuración de un nodo antes de guardar
Llama al endpoint Validar la configuración de un nodo (POST /v1/catalog/executors/{id}/validate) para verificar la configuración de un nodo contra el JSON Schema del ejecutor del catálogo.
Esto hace solo validación de JSON Schema. Verifica que tu objeto de configuración coincida con la estructura que espera el ejecutor del catálogo (campos obligatorios, tipos, formatos). No llama al servicio externo, así que el primer viaje de ida y vuelta real ocurre cuando un workflow ejecuta el nodo.
Pasa mappedTargets para nombrar los campos que tu nodo suministra a través de un inputMapping en lugar de un valor fijo. Esos campos cuentan como satisfechos, así que un nodo que mapea un campo obligatorio desde el disparador se valida antes de que lo guardes.
Mapeo de campos y transformación de datos
Usa los mapeos de campos y las transformaciones cuando los datos del workflow no coinciden con el formato que espera un servicio externo. Úsalos también cuando un servicio devuelve datos con una forma que el siguiente paso no puede consumir. Defines los mapeos de campos y las transformaciones dentro del objeto
data de los nodos ejecutores. 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 la espera el servicio externo. No hay objeto envoltorio ni prefijo que agregar. Un source de salida es una ruta dentro del envelope de la respuesta, así que los campos de la respuesta quedan bajo body.
Ejemplo rápido: mapear campos del workflow a un nodo ejecutor
Ejemplo rápido: mapear campos del workflow a un nodo ejecutor
${executor-balance.balance}.Paso 4: Ejecuta el workflow
Referencia la configuración de proveedor en un nodo de workflow de tipo
executor.
El ejemplo de abajo 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 la puntuación de riesgo y aprueba o rechaza el pago según el resultado.
El workflow tiene cinco nodos. Un disparador de webhook recibe el pago, y un nodo ejecutor llama al servicio de verificación de fraude. Un nodo condicional evalúa la puntuación, y hay dos nodos de acción para los resultados de aprobación y rechazo. Las aristas los conectan en secuencia, y el nodo condicional se ramifica hacia cualquiera de los dos caminos según el umbral de la puntuación.
Usa el endpoint Crear workflow para definir el workflow, luego Actívalo y por último 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. También nombra la configuración FraudShield del Paso 2, que contiene la URL base y las credenciales. Ambos lados nombran al mismo proveedor, así que el workflow se guarda. Flowker envía la solicitud a https://api.fraudshield.example.com/score-transaction.El nodo no declara outputMapping, así que su salida conserva la forma del envelope de la respuesta. Por eso la puntuación queda en check-fraud.body.score, que es lo que lee la condición evaluate-score. Agrega 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
Disparas las ejecuciones de workflow mediante el endpoint Ejecutar workflow:
inputData de la ejecución. Todos los campos están disponibles para los nodos siguientes mediante el namespace workflow (por ejemplo, workflow.transactionId o workflow.amount). Las salidas de los nodos están disponibles mediante el ID del nodo (por ejemplo, check-fraud.body.score para un nodo que no declara outputMapping).
Idempotencia
Cada solicitud de ejecución debe incluir un headerIdempotency-Key. Una solicitud sin él falla con 400 Bad Request (error FLK-0509). Genera un UUID nuevo para cada ejecución nueva, y reutiliza la misma clave solo cuando reintentas la solicitud idéntica.
Disparadores de webhook
Los webhooks son la vía principal por la que los sistemas externos disparan workflows de Flowker. En lugar de que tu sistema llame a la API de ejecuciones directamente, registras un path de webhook en un workflow. Los servicios externos envían entonces solicitudes HTTP a ese path.
Cómo funciona
- Agrega a tu workflow un nodo disparador de tipo
webhookcon unpathy unmethoden sudata. Estableceinput_contractde forma explícita en los nodos nuevos cuando necesites validaciónopen,xsdoopenapi. - Cuando activas el workflow, 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 nodo disparador de webhook
El disparador de webhook es un nodo contype: "trigger" y triggerType: "webhook" en su data, más un path, un method y un input_contract opcional. Configurar un disparador de webhook cubre cada campo, los tres modos de input_contract y lo que requiere cada uno, y lleva un nodo resuelto para cada modo.
La configuración del disparador sigue un contrato cerrado. Guardar un workflow falla con FLK-0934 cuando su disparador de webhook omite path o method, o le falta un campo que requiere el modo de input_contract seleccionado. También falla cuando el disparador nombra el id de esquema o el campo de operación de otro modo. Falla también cuando el disparador lleva una clave o un valor que el esquema no acepta. Una declaración de accepted_headers inválida falla en cambio con FLK-0957.
El esquema también declara los campos opcionales response_mode, response_view y accepted_headers. Consulta Configurar un disparador de webhook.
Asegurar 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 de OIDC), y quien llama debe tener el permiso execute sobre el recurso webhooks. Una solicitud sin un token válido falla con 401 Unauthorized.
Otorga ese permiso a una identidad máquina a máquina para cada sistema al que dejas llamar a tus webhooks, y gestiona la concesión en Access Manager. Esto mantiene el acceso a los 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 nodos del workflow mediante el namespace
workflow._webhook.
Notas importantes
- Solo un workflow activo puede registrar cada combinación de path + método de webhook. Activar un segundo workflow con el mismo path falla con un error de conflicto.
- Los paths de webhook admiten segmentos anidados (por ejemplo,
payments/stripe/received). - El tamaño máximo del cuerpo de la solicitud es 1 MB.
- Desactivar un workflow da de baja automáticamente sus rutas de webhook.
Modo de respuesta síncrono
De forma predeterminada, un disparador de webhook responde con un comprobante202 en cuanto la ejecución empieza (el modo asíncrono). Quien llama debe consultar el estado de la ejecución por separado. Establece response_mode en "sync" en el data del nodo disparador para que Flowker mantenga abierta la conexión HTTP y devuelva el resultado de la ejecución directamente en la respuesta:
Si la ejecución no alcanza un estado terminal antes de que transcurra el límite interno de espera, Flowker recurre al comprobante
202 del modo asíncrono. Ese comprobante lleva un header Location que apunta al endpoint de resultados.
response_view selecciona la forma del cuerpo de la respuesta síncrona:
El
finalOutput de una ejecución fallida (en la vista full o final_output) siempre lleva status: "failed" y errorMessage, y errorClass cuando Flowker pudo clasificar la falla, nunca un {} vacío. Sin una anulación responseStatusCode (ver más abajo), el estado HTTP síncrono se mantiene en 200 para full/final_output/receipt (reporta la salud del transporte, no el resultado de negocio). Un responseStatusCode válido en el nodo set_output terminal anula ese estado para esas tres vistas.
Un nodo de acción con actionType: "set_output" puede llevar un responseStatusCode opcional (entero, 200–599) para anular el estado HTTP que devuelve una respuesta de webhook sync. Un valor fuera de rango o que no es entero falla al guardar (FLK-0122). Para passthrough, la anulación aplica solo cuando el propio nodo set_output es el paso terminal. El estado del proveedor retransmitido por un ejecutor terminal siempre gana, y el respaldo sin respuesta siempre usa un 200 simple para que una anulación nunca enmascare una falla.
La detección de passthrough es estricta: solo cuenta el paso terminal. Un set_output terminal downstream de un ejecutor da forma a la respuesta como su propia salida. Flowker nunca retrocede a la respuesta de un ejecutor anterior. En una ejecución fallida el paso que detiene es el paso terminal, así que Flowker retransmite un 4xx del proveedor que detuvo el workflow como el 4xx real.
Los valores de la salida de un nodo set_output admiten referencias ${...} resueltas contra el contexto del workflow, incluidas ${workflow.<field>} (payload del disparador), ${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 paso (fail-closed).
Tratamiento de errores
Si un nodo falla, la ejecución se detiene y su estado pasa a
failed.
No hay respaldo automático. Después de que se agotan los reintentos, la ejecución falla.
Los resultados de la ejecución reportan el status de la ejecución y los stepResults. Un paso fallido proporciona stepNumber, nodeId, status y errorMessage, con statusCode y errorClass cuando están disponibles. El campo output es opcional. No prometas un errorCode, incluidos FLK-0504 o FLK-0507, en cada payload de resultados de ejecución.
Reintento y circuit breaker
Flowker incluye resiliencia integrada para las llamadas de ejecutor.
Reintentos
Cuando una llamada de ejecutor falla con un error transitorio (un error de red, un timeout en el intento, cualquier estado5xx, o el estado 408 o 429), Flowker reintenta automáticamente. El comportamiento de reintento se configura por nodo, en el data del nodo ejecutor:
Los reintentos aplican solo cuando la operación es segura de repetir. De forma predeterminada, Flowker trata las llamadas
POST y PATCH como no idempotentes y no las reintenta (un solo intento), mientras que GET, PUT, DELETE y los demás verbos reintentan con normalidad. Un retry.max_attempts mayor que 1 activa los reintentos en ese nodo sea cual sea el método. Un retry.max_attempts de 1 no es una activación. Establece un solo intento.
Los errores no reintentables cortocircuitan a un solo intento sin importar la configuración. Son: circuit breaker abierto, contexto cancelado, errores de configuración y fallas de resolución de secretos. También incluyen un cuerpo de solicitud que supera el límite de tamaño configurado, un cuerpo de respuesta del proveedor que supera ese mismo límite y respuestas 4xx no transitorias del proveedor. Eso significa cualquier 4xx salvo 408 y 429.
El reintento aplica por ejecución de nodo. Si todos los intentos fallan, el paso falla y la ejecución se detiene.
Circuit breaker
Flowker usa un circuit breaker para que las llamadas fallidas repetidas no saturen los servicios externos:
Los errores
4xx de cliente o de autenticación del proveedor no disparan el circuito: son el problema de quien llama, no una señal de que el proveedor está caído. Solo las fallas de nivel de transporte y las 5xx cuentan para el umbral.
Cuando el circuito está abierto, las llamadas de ejecutor fallan de inmediato con FLK-0507 en lugar de llegar al servicio externo. Esto evita las fallas en cascada y da tiempo al servicio externo para recuperarse.
Transiciones de estado del circuit breaker
Registro de configuraciones de ejecutor
Este registro es un tercer uso, separado, de la palabra “executor”. Sus entradas no son los ejecutores del catálogo del Paso 1. No son los nodos de workflow de
type: "executor", ni las configuraciones de proveedor del Paso 2. El motor lee las configuraciones de proveedor para llamar a servicios externos, no estas entradas, y el registro lleva su propio vocabulario de campos (baseUrl, endpoints, authentication). El registro expone cuatro operaciones:
Cada entrada lleva un
status, que la API reporta 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 query. La actualización aplica a las entradas en estado unconfigured o configured. La eliminación aplica a las entradas en 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.
Qué sigue
Conceptos centrales
Entiende los workflows, los nodos, las aristas y las ejecuciones.
API de configuraciones de proveedor
Explora la API de configuración de proveedor.