Skip to main content
Flowker se conecta a servicios externos (como motores anti-fraude, procesadores de pago, proveedores KYC y más) a través de configuraciones de executor. En esta guía, explorarás el catálogo, configurarás una conexión de executor, probarás conectividad, lo usarás en un workflow y entenderás el modelo de resiliencia de Flowker.

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

Ciclo de vida de la configuración de executor

Las configuraciones de executor se gestionan a través de los endpoints /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.

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.
Piensa en el catálogo como un menú: muestra a qué puede conectarse Flowker. Las configuraciones de executor son tus pedidos específicos — las credenciales, URLs y configuraciones para cada servicio que quieres usar.

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 a POST /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.
Para integraciones OAuth 2.0, usa oidc_client_credentials. Flowker gestiona la obtención y renovación del token automáticamente.

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 el providerId 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.

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 estado active. 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.
Para integraciones complejas, también puedes adjuntar transformaciones a entradas de mapeo individuales (p. ej., eliminar caracteres, agregar prefijos, cambiar capitalización) y definir operaciones de Kazaam para transformaciones avanzadas JSON-a-JSON. Consulta la Referencia de mapeo de campos para ver la lista completa de tipos de transformación, estructuras JSON y guía de solución de problemas.

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.

Disparar workflows


Las ejecuciones de workflows se disparan a través del endpoint Ejecutar workflow:
El cuerpo de la solicitud contiene el 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 header Idempotency-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

  1. Agrega un node trigger de tipo webhook a tu workflow con un path y method en su data.
  2. Cuando el workflow se activa, Flowker registra la ruta en su registro de webhooks.
  3. Los sistemas externos envían solicitudes a POST /v1/webhooks/{path} (o el método que configuraste).
  4. Flowker resuelve la ruta hacia el workflow correspondiente y lo ejecuta.

Definir un node trigger de webhook

El trigger de webhook es un node con type: "trigger" y los siguientes campos en data:
Una vez que este workflow se activa, los sistemas externos pueden dispararlo enviando:

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.
Consulta la referencia de la API Disparar un webhook para la documentación completa del endpoint.

Modo de respuesta síncrona

Por defecto, un trigger de webhook responde con un recibo 202 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, 200599) 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.
Estados del circuit breaker

Transiciones de estado del circuit breaker

El circuito comienza en estado Closed, donde todas las solicitudes pasan normalmente. Al alcanzar el umbral de fallas, transiciona a Open, bloqueando todas las solicitudes inmediatamente. Después de 30 segundos, pasa a Half-Open y permite una solicitud de prueba. Si esa solicitud tiene éxito, el circuito vuelve a Closed. Si falla, el circuito se reabre por otro ciclo de 30 segundos.
El circuit breaker opera por configuración de executor. Las fallas en un executor no afectan a otros. Los umbrales del circuit breaker (cantidad de fallas, timeout de recuperación) son valores globales configurados en el deployment — no se pueden personalizar por executor en esta versión.

Próximos pasos


Conceptos fundamentales

Comprende workflows, nodes, edges y ejecuciones.

Executor configurations API

Explora la API de configuración de executors.