Guía de integración

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:

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.

Status	Qué significa	Siguiente paso
`unconfigured`	Creado con detalles de conexión pero no completamente configurado.	Configurarlo (PATCH)
`configured`	Detalles de conexión definidos y validados.	Probar conectividad
`tested`	Prueba de conectividad exitosa.	Activarlo
`active`	Disponible para ejecución de workflows.	—
`disabled`	Temporalmente fuera de servicio.	Habilitarlo

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.

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.

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.

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:

Operación	Endpoint
Listar	`GET /v1/executors`
Obtener	`GET /v1/executors/{id}`
Actualizar	`PATCH /v1/executors/{id}`
Eliminar	`DELETE /v1/executors/{id}`

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.

Tipo	Descripción	Campos de configuración
`none`	Sin autenticación.	—
`api_key`	API key en header o query.	`key`, `value`, `location`
`bearer`	Bearer token en el header Authorization.	`token`
`basic`	Usuario y contraseña (Base64).	`username`, `password`
`oidc_client_credentials`	Flujo OAuth 2.0 client credentials con gestión automática de tokens.	`tokenURL`, `clientID`, `clientSecret`, `scopes`
`oidc_user`	Flujo OAuth 2.0 resource owner password.	`tokenURL`, `clientID`, `clientSecret`, `username`, `password`, `scopes`

Para integraciones OAuth 2.0, usa oidc_client_credentials. Flowker gestiona la obtención y renovación del token automáticamente.

Ejemplo — OIDC client credentials

{
  "authentication": {
    "type": "oidc_client_credentials",
    "config": {
      "tokenURL": "https://auth.fraudshield.com/oauth/token",
      "clientID": "flowker-integration",
      "clientSecret": "secret-value",
      "scopes": ["transactions:read", "transactions:score"]
    }
  }
}

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.

Ejemplo de solicitud

POST /v1/provider-configurations

{
  "name": "Midaz Production",
  "description": "Instancia Midaz de producción para operaciones de saldo",
  "providerId": "midaz",
  "config": {
    "base_url": "https://midaz.example.com/api/v1",
    "api_key": "sk-prod-xxx"
  },
  "metadata": {
    "environment": "production"
  }
}

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.

Ejemplo rápido — mapear campos del workflow a un executor

{
  "id": "executor-balance",
  "type": "executor",
  "name": "Check Balance",
  "data": {
    "providerConfigId": "a1b2c3d4-e5f6-4789-a012-345678901234",
    "inputMapping": [
      { "source": "workflow.customerId", "target": "executor.accountId" },
      { "source": "workflow.amount", "target": "executor.minimumBalance" }
    ],
    "outputMapping": [
      { "source": "executor.currentBalance", "target": "workflow.balance" },
      { "source": "executor.accountStatus", "target": "workflow.status" }
    ]
  }
}

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.

Ejemplo — Crear un workflow de validación de pagos

POST /v1/workflows

{
  "name": "payment-validation",
  "description": "Valida un pago antes de procesarlo.",
  "nodes": [
    {
      "id": "trigger-payment",
      "type": "trigger",
      "name": "Payment received",
      "position": { "x": 0, "y": 0 },
      "data": { "triggerType": "webhook" }
    },
    {
      "id": "check-fraud",
      "type": "executor",
      "name": "Fraud check",
      "position": { "x": 200, "y": 0 },
      "data": {
        "providerConfigId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
        "endpointName": "score-transaction"
      }
    },
    {
      "id": "evaluate-score",
      "type": "conditional",
      "name": "Score evaluation",
      "position": { "x": 400, "y": 0 },
      "data": {
        "condition": "check-fraud.score < 80"
      }
    },
    {
      "id": "approve",
      "type": "action",
      "name": "Approve payment",
      "position": { "x": 600, "y": -100 },
      "data": { "action": "log" }
    },
    {
      "id": "reject",
      "type": "action",
      "name": "Reject payment",
      "position": { "x": 600, "y": 100 },
      "data": { "action": "log" }
    }
  ],
  "edges": [
    { "id": "e1", "source": "trigger-payment", "target": "check-fraud" },
    { "id": "e2", "source": "check-fraud", "target": "evaluate-score" },
    { "id": "e3", "source": "evaluate-score", "target": "approve", "condition": "true" },
    { "id": "e4", "source": "evaluate-score", "target": "reject", "condition": "false" }
  ]
}

Ejemplo — Ejecutar el workflow

POST /v1/workflows/{workflowId}/executions
Idempotency-Key: {unique-uuid}

{
  "inputData": {
    "transactionId": "txn-98765",
    "amount": 1500.00,
    "currency": "BRL",
    "customerId": "cust-12345"
  }
}

Disparar workflows

Las ejecuciones de workflows se disparan a través del endpoint Ejecutar workflow:

POST /v1/workflows/:workflowId/executions

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

Para prevenir ejecuciones duplicadas, incluye un header Idempotency-Key en la solicitud. Si no se proporciona un Idempotency-Key, la protección contra duplicados no está garantizada.

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 webhook a tu workflow con un path y method en su data.
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 con type: "trigger" y los siguientes campos en data:

Campo	Tipo	Requerido	Descripción
`triggerType`	string	Sí	Debe ser `"webhook"`.
`path`	string	Sí	La ruta del webhook a registrar (p. ej., `"payments/received"`).
`method`	string	Sí	Método HTTP que debe coincidir (p. ej., `"POST"`).
`verify_token`	string	No	Token estático para la verificación del webhook. Cuando está definido, las solicitudes deben incluir un header `X-Webhook-Token` coincidente.

Ejemplo — Node trigger de webhook

{
  "id": "trigger-1",
  "type": "trigger",
  "name": "Payment Webhook",
  "position": { "x": 0, "y": 0 },
  "data": {
    "triggerType": "webhook",
    "path": "payments/received",
    "method": "POST",
    "verify_token": "my-secret-token"
  }
}

Una vez que este workflow se activa, los sistemas externos pueden dispararlo enviando:

POST /v1/webhooks/payments/received
X-Webhook-Token: my-secret-token
Content-Type: application/json

{ "transactionId": "txn-123", "amount": 1500.00 }

Metadata del webhook

Flowker inyecta automáticamente un objeto _webhook en el inputData de la ejecución con metadata sobre la solicitud entrante:

Campo	Descripción
`_webhook.method`	Método HTTP usado (p. ej., `POST`).
`_webhook.path`	La ruta del webhook resuelta.
`_webhook.headers`	Headers de la solicitud (excluyendo `Authorization`, `X-API-Key` y `X-Webhook-Token`).
`_webhook.query`	Parámetros del query string.
`_webhook.remote_ip`	Dirección IP del llamador.

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.

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

Código de error	Significado	Acción
`FLK-0504`	Ejecución de node fallida.	Revisa los resultados del paso y la respuesta del servicio externo.
`FLK-0507`	Circuit breaker abierto.	Espera la recuperación o verifica la salud del servicio.

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:

Reintentos máximos: 5 intentos
Estrategia de backoff: Exponencial — 1s, 2s, 4s, 8s
Errores no reintentables: Circuit breaker abierto, contexto cancelado, configuración inválida

El reintento aplica por ejecución de node. Si los 5 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:

Parámetro	Valor
Umbral de fallas	5 fallas consecutivas abren el circuito
Timeout de recuperación	30 segundos antes de reintentar (estado half-open)
Solicitudes half-open	1 solicitud permitida para probar la recuperación

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.

El circuito comienza en estado Closed, donde todas las solicitudes pasan normalmente. Después de 5 fallas consecutivas, 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 al inicio — no se pueden personalizar por executor en esta versión.

Introducción

Guías

Operaciones

Guía de integración

Ciclo de vida de la configuración de executor

Paso 1: Explorar el catálogo

Paso 2: Configurar una conexión de provider y el executor

Crear una configuración de provider

Gestionar configuraciones de executor

Tipos de autenticación

Configuraciones de provider

Crear una configuración de provider

Probar conectividad

Habilitar y deshabilitar

Paso 3: Configurar el executor

Paso 4: Valida tu configuración

Mapeo de campos y transformación de datos

Paso 5: Usar el executor en un workflow

Usar un executor en un workflow

Disparar workflows

Idempotencia

Triggers por webhook

Cómo funciona

Definir un node trigger de webhook

Metadata del webhook

Notas importantes

Manejo de errores

Reintentos y circuit breaker

Reintentos

Circuit breaker

Próximos pasos

Conceptos fundamentales

Executor configurations API

Introducción

Guías

Operaciones

​Ciclo de vida de la configuración de executor

​Paso 1: Explorar el catálogo

​Paso 2: Configurar una conexión de provider y el executor

​Crear una configuración de provider

​Gestionar configuraciones de executor

​Tipos de autenticación

​Configuraciones de provider

​Crear una configuración de provider

​Probar conectividad

​Habilitar y deshabilitar

​Paso 3: Configurar el executor

​Paso 4: Valida tu configuración

​Mapeo de campos y transformación de datos

​Paso 5: Usar el executor en un workflow

​Usar un executor en un workflow

​Disparar workflows

​Idempotencia

​Triggers por webhook

​Cómo funciona

​Definir un node trigger de webhook

​Metadata del webhook

​Notas importantes

​Manejo de errores

​Reintentos y circuit breaker

​Reintentos

​Circuit breaker

​Próximos pasos

Conceptos fundamentales

Executor configurations API

Ciclo de vida de la configuración de executor

Paso 1: Explorar el catálogo

Paso 2: Configurar una conexión de provider y el executor

Crear una configuración de provider

Gestionar configuraciones de executor

Tipos de autenticación

Configuraciones de provider

Crear una configuración de provider

Probar conectividad

Habilitar y deshabilitar

Paso 3: Configurar el executor

Paso 4: Valida tu configuración

Mapeo de campos y transformación de datos

Paso 5: Usar el executor en un workflow

Usar un executor en un workflow

Disparar workflows

Idempotencia

Triggers por webhook

Cómo funciona

Definir un node trigger de webhook

Metadata del webhook

Notas importantes

Manejo de errores

Reintentos y circuit breaker

Reintentos

Circuit breaker

Próximos pasos