Conectar tu propia API

Flowker trae conectores para los servicios de su catálogo. Cuando el servicio que quieres llamar es tuyo — una API interna, la API de un partner, cualquiera con un documento OpenAPI publicado — subes ese documento y un node de workflow llama a sus operaciones directamente. Haces esto una vez por documento: lo subes, creas una configuración de provider que apunta hacia él y después direccionas una operación desde cada node que llama al servicio.

Antes de empezar

El documento OpenAPI 3.x de tu servicio como archivo, de 8 MiB como máximo, que declare al menos una operación.
Las credenciales que exige tu servicio y el método de autenticación que espera. Consulta Autenticación para ver los métodos que admite Flowker.
Un despliegue cuyo registro de esquemas tenga almacenamiento de blobs configurado. SCHEMA_REGISTRY_S3_BUCKET guarda los documentos OpenAPI que subes — consulta Variables de entorno de Flowker.
Un workflow en estado draft para editar. Un workflow activo queda bloqueado, así que llama primero a Mover el workflow a draft y actívalo de nuevo después.

La Lerian Console cubre el mismo camino. Providers → + New Provider → Add your own API selecciona un documento ya subido y define la URL base y la autenticación — consulta Agregar un provider.

Paso 1: Sube el documento OpenAPI

Envía el archivo

Llama a Subir un esquema OpenAPI como multipart/form-data con tres partes: el file, un name y una version.

curl -X POST https://tu-host-flowker/v1/openapi-schemas \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@acme-kyc.json" \
  -F "name=acme-kyc" \
  -F "version=v1.0.0"

Guarda el id

La respuesta 201 describe lo que Flowker leyó del archivo. Su id es el valor que referencia cada paso posterior.

Campo	Lo que te dice
`id`	El identificador del documento. Una configuración de provider y un trigger de webhook apuntan hacia él.
`name`, `version`	El par que enviaste.
`title`	El `info.title` del documento.
`openapiVersion`	La versión `openapi` que declara el documento.
`operationCount`	Cuántas operaciones de ruta y método declara el documento.
`contentHash`, `byteSize`	El digest y el tamaño del archivo almacenado.
`createdBy`, `createdAt`	Quién lo subió y cuándo.

Por qué clave se identifica un documento almacenado

name y version los eliges tú, con hasta 255 caracteres cada uno. El par es único en tu tenant: subir de nuevo el mismo name y la misma version responde FLK-0812. El id que devuelve Flowker es un UUID nuevo en cada subida, y es lo que referencia todo lo demás — nunca el nombre ni la versión. Flowker analiza el archivo antes de almacenarlo. Un archivo que no es un documento OpenAPI 3.x, o que no declara ninguna operación, responde FLK-0900. Un archivo de más de 8 MiB responde FLK-0901. Tus documentos subidos son solo tuyos. Un documento solo es visible para el tenant que lo subió, y un id de otro tenant nunca se resuelve.

Paso 2: Consulta las operaciones que puedes llamar

Lista lo que tienes almacenado

Listar esquemas OpenAPI devuelve tus documentos solo como metadatos, sin su contenido. Está paginado: limit, cursor, sortBy y sortOrder, y la respuesta trae nextCursor y hasMore.

Consulta las operaciones de un documento

Obtener un esquema OpenAPI devuelve los mismos metadatos más content — el archivo almacenado — y operations, una entrada por cada operación que declara el documento.

Campo	Lo que te dice
`path`	La ruta de la operación, exactamente como la escribe el documento, como `/v1/checks`.
`method`	El método HTTP de la operación.
`operationId`	El `operationId` del documento, cuando declara uno.
`hasRequest`	Si la operación declara un cuerpo de solicitud JSON.
`hasResponse`	Si la operación declara una respuesta correcta JSON.

Copia el path y el method de la operación que quieres. El Paso 4 los pone en el node.

Consulta los nombres de campo de una operación

Derivar el esquema de una operación recibe un path y un method y devuelve inputSchema — el cuerpo de la solicitud de la operación — y outputSchema — su respuesta correcta. También devuelve params, una entrada por cada parámetro que declara la operación, cada una con su name, su ubicación in y si es required.Esos son los nombres de campo que escribes como target y como source de tus mapeos en el Paso 4. Los dos parámetros de consulta son obligatorios, y el method no distingue mayúsculas y debe ser uno de GET, PUT, POST, DELETE, OPTIONS, HEAD, PATCH o TRACE; un path ausente o un method no reconocido responden FLK-0304. Una ruta y un método que el documento no declara responden FLK-0902.

Paso 3: Apunta una configuración de provider hacia el documento

Llama a Crear una configuración de provider con kind en external_openapi. Ese kind es la conexión que trae tu propio OpenAPI: referencia el documento que subiste en lugar de un provider del catálogo.

Campo	Obligatorio	Descripción
`kind`	Sí	`"external_openapi"`. Eliges el kind al crear la configuración, y se queda con el kind con el que la creaste.
`providerId`	No	Omítelo: esta conexión apunta a tu propio documento, no a un provider del catálogo. Una lectura de la configuración devuelve entonces el id reservado `external.openapi`.
`name`	Sí	Un nombre para esta conexión, de 1 a 100 caracteres.
`config.openapi_schema_id`	Sí	El `id` del Paso 1. Debe nombrar un documento de tu tenant.
`config.base_url`	No	El esquema, el host y el prefijo de ruta a los que Flowker envía las solicitudes. Omítelo para usar la primera entrada `servers` utilizable del documento.
`config.auth`	No	Un bloque de autenticación `{ type, config }`, con la misma forma que usa cualquier configuración de provider. Consulta Autenticación para cada tipo y sus campos. Omítelo para un servicio que no exige autenticación.
`allowedHosts`	No	Los hosts a los que esta configuración puede llamar. Omítelo, o envía una lista vacía, para aceptar cualquier host público.
`allowedPrivateHosts`	No	Hosts privados nombrados a los que esta configuración puede llegar. Las direcciones de metadatos de nube y link-local siguen bloqueadas.
`schemaBindings`	No	Los documentos almacenados a los que se vincula esta configuración. Consulta Vincula el documento.
`description`	No	Texto libre, hasta 500 caracteres.
`metadata`	No	Tus propios pares clave-valor.

Dónde va la credencial

El secreto dentro de config.auth es de solo escritura. Flowker lo envía a tu backend de secretos, lo elimina del documento de configuración antes de guardar el documento y lo resuelve desde el backend en el momento de la ejecución. Ninguna ruta de configuración de provider lo devuelve. Cualquier otra cosa que coloques en el documento de configuración se almacena con la configuración, y una lectura puede devolverla — así que pon cada credencial en config.auth. Para rotar un secreto más adelante, envía el nuevo valor en una actualización. Para mantener el actual, omite el campo o envíalo vacío mientras auth.type no cambie — consulta Autenticación.

Dónde se definen las listas de hosts permitidos

Las dos listas pertenecen a esta llamada de creación, y después a Actualizar una configuración de provider. allowedHosts nombra los hosts a los que puede llegar cada node que llama a través de esta configuración; Flowker comprueba contra ella la URL de la solicitud y cada salto de redirección en tiempo de ejecución. Una entrada con un punto inicial coincide con los subdominios, así que .acme-kyc.example.com coincide con api.acme-kyc.example.com. Las entradas son solo nombres de host, sin literal de IP, sin comodín y sin puerto. allowedPrivateHosts es la lista compañera para un servicio que vive en una red privada. Una entrada permite que esta configuración llegue a un host que resuelve a una dirección privada o de loopback, que Flowker bloquea por defecto. Las direcciones de metadatos de nube y link-local siguen bloqueadas, y ninguna entrada las alcanza.

Vincula el documento

Agrega una entrada schemaBindings para el documento que referenciaste. Cada entrada nombra un documento almacenado: type es "openapi", schemaId es el mismo id que pusiste en config.openapi_schema_id, y el array opcional operations restringe el vínculo a las operaciones que tus workflows llaman de verdad. El vínculo es lo que hace visibles los dependientes del documento. Con él, Listar los recursos que referencian un esquema OpenAPI informa esta configuración, y un borrado del documento se rechaza mientras la configuración esté activa — consulta Eliminar un documento. Flowker resuelve cada vínculo cuando guardas. Un schemaId que no nombra ningún documento de tu tenant responde FLK-0942, y una entrada de operations que el documento no declara responde FLK-0943, cada uno nombrando la entrada que falló. Una entrada mal formada — un type desconocido, un schemaId que no es un UUID, operations en un vínculo que no es openapi, o una operación sin ruta ni método — responde FLK-0293.

Ejemplo de solicitud

POST /v1/provider-configurations

{
  "name": "Acme KYC production",
  "description": "Production KYC checks",
  "kind": "external_openapi",
  "config": {
    "openapi_schema_id": "018f3e2a-1c4d-7b9e-a1b2-c3d4e5f6a7b8",
    "base_url": "https://api.acme-kyc.example.com",
    "auth": {
      "type": "api_key",
      "config": {
        "key": "sk-live-xxx",
        "header_name": "X-API-Key",
        "location": "header"
      }
    }
  },
  "allowedHosts": ["api.acme-kyc.example.com"],
  "schemaBindings": [
    {
      "type": "openapi",
      "schemaId": "018f3e2a-1c4d-7b9e-a1b2-c3d4e5f6a7b8",
      "operations": [
        { "path": "/v1/checks", "method": "POST" },
        { "path": "/v1/checks/{checkId}", "method": "GET" }
      ]
    }
  ]
}

La respuesta devuelve el id de la nueva configuración. Guárdalo — el Paso 4 lo pone en el providerConfigId de cada node que llama a este servicio.

Flowker comprueba la configuración antes de almacenarla. Un config sin openapi_schema_id, o cuyo valor no es un UUID, responde FLK-0946. Un id que no nombra ningún documento de tu tenant responde FLK-0947. Un bloque config.auth que Flowker no puede leer — un tipo desconocido, o un tipo al que le falta uno de sus campos obligatorios — responde FLK-0948. En este punto no se hace ninguna llamada de red.

Paso 4: Direcciona una operación desde un node de workflow

Un node executor nombra una operación del documento con dos campos en su data, junto al providerConfigId de la configuración del Paso 3.

Campo	Obligatorio	Descripción
`providerConfigId`	Sí	El UUID de la configuración de provider que apunta hacia el documento.
`operation_path`	Sí	La ruta de la operación, exactamente como la escribe el documento, incluidas sus plantillas de parámetro `{...}`.
`operation_method`	Sí	El método HTTP de la operación. La coincidencia no distingue mayúsculas.
`inputMapping`	No	Mueve valores del contexto del workflow a la solicitud. Cada `target` es una ruta del cuerpo de la solicitud, o el nombre de un parámetro.
`outputMapping`	No	Mueve valores fuera de la respuesta para que los lean los nodes posteriores.

No envíes executorId en un node así. Flowker resuelve la configuración de provider, reconoce el kind y rellena el campo por ti antes de validar el workflow. Todos los demás campos del node se comportan como describe Referenciar la configuración de provider desde un node de workflow.

Cómo se arma la solicitud

Flowker lee la operación del documento almacenado en tiempo de ejecución y arma la solicitud a partir de ella:

El destino es config.base_url cuando la configuración lo define, y en su defecto la primera entrada servers utilizable del documento, unida con operation_path.
Un parámetro path toma su valor primero de los datos resueltos del node, y en segundo lugar del cuerpo de la solicitud. Todo parámetro path necesita un valor.
Un parámetro query o header se resuelve igual, y se omite cuando no se encuentra ningún valor.
El cuerpo de la solicitud es lo que arma tu inputMapping. Escribe cada target exactamente como lo nombra el esquema de solicitud de la operación: no hay objeto envolvente ni prefijo que agregar. Trabajar con los datos de la solicitud y de la respuesta cubre los mapeos y las transformaciones por completo.

Ejemplo — un workflow que llama a dos operaciones del documento

POST /v1/workflows

{
  "name": "kyc-check",
  "description": "Opens a KYC check on the Acme API and records the result.",
  "nodes": [
    {
      "id": "kyc-received",
      "type": "trigger",
      "name": "KYC request received",
      "position": { "x": 0, "y": 0 },
      "data": {
        "triggerType": "webhook",
        "path": "kyc/requested",
        "method": "POST",
        "input_contract": "open",
        "format": "json"
      }
    },
    {
      "id": "open-check",
      "type": "executor",
      "name": "Open KYC check",
      "position": { "x": 200, "y": 0 },
      "data": {
        "providerConfigId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
        "operation_path": "/v1/checks",
        "operation_method": "POST",
        "inputMapping": [
          { "source": "workflow.documentNumber", "target": "documentNumber" },
          { "source": "workflow.fullName", "target": "fullName" }
        ],
        "outputMapping": [
          { "source": "body.checkId", "target": "checkId" },
          { "source": "body.status", "target": "status" }
        ]
      }
    },
    {
      "id": "record-check",
      "type": "action",
      "name": "Record the check",
      "position": { "x": 400, "y": 0 },
      "data": {
        "actionType": "set_output",
        "output": {
          "checkId": "${open-check.checkId}",
          "status": "${open-check.status}"
        }
      }
    }
  ],
  "edges": [
    { "id": "e1", "source": "kyc-received", "target": "open-check" },
    { "id": "e2", "source": "open-check", "target": "record-check" }
  ]
}

El node open-check envía POST https://api.acme-kyc.example.com/v1/checks con el cuerpo que armó su inputMapping. Su outputMapping extrae dos campos de la respuesta, así que el node siguiente lee ${open-check.checkId}.Un node que llama a GET /v1/checks/{checkId} lee el parámetro del mismo ámbito del node. Mapea un valor a checkId y Flowker lo sustituye en la ruta.

Un trigger de webhook puede validar el payload entrante contra una operación del mismo documento. Pon input_contract en "openapi" y dale al trigger openapi_schema_id, operation_path y operation_method — consulta Configurar un trigger de webhook.

Paso 5: Ejecútalo y confirma que funcionó

Activa el workflow

Llama a Activar un workflow. La activación registra la ruta de webhook y resuelve lo que referencia el contrato del trigger.

Ejecútalo

Llama a Ejecutar un workflow con una cabecera Idempotency-Key nueva, o envía una solicitud a la ruta de webhook.

Lee los resultados de los pasos

Un node que llegó a tu servicio registra la respuesta bajo su propio id. Con un outputMapping, los nombres mapeados quedan directamente bajo ese id — open-check.checkId. Sin outputMapping, la salida del node conserva el envoltorio de la respuesta, así que el cuerpo de la respuesta queda un nivel más abajo, bajo body.

Publicar una nueva versión de tu documento

Un documento almacenado no cambia. Para publicar una revisión, sube el archivo de nuevo con una version nueva; eso te da un segundo documento almacenado con su propio id. Nada cambia por sí solo. Toda referencia es por id, así que un workflow que ya está en marcha sigue llamando al documento que referencia. Para moverlo, envía el config de la configuración de provider con el nuevo openapi_schema_id mediante Actualizar una configuración de provider. config reemplaza el mapa almacenado en lugar de fusionarse con él, así que incluye base_url y auth en la misma llamada. Flowker revalida el nuevo id contra tu tenant, y responde FLK-0947 cuando no se resuelve. Consulta Listar los recursos que referencian un esquema OpenAPI sobre el documento anterior antes de retirarlo — nombra todo lo que todavía apunta hacia él.

Versiones de especificación de los servicios del catálogo

Los servicios propios del catálogo de Flowker se resuelven contra un registro compartido de especificaciones publicadas, aparte. Tres operaciones lo gestionan. Nunca tocan un documento que subiste en el Paso 1.

Operación	Lo que hace
Listar versiones de especificación OpenAPI	Lista en `versions` las versiones publicadas de la especificación de un servicio, e informa en `pinnedVersion` la que fijó tu tenant. `pinnedVersion` está vacío cuando tu tenant no fijó ninguna.
Fijar una versión de especificación OpenAPI	Selecciona la versión contra la que se resuelve tu tenant para ese servicio. Es idempotente: fijar de nuevo reemplaza la versión en el sitio. Una solicitud sin el servicio o sin la versión responde `FLK-0801`.
Subir una versión de especificación OpenAPI	Publica una versión de la especificación de un servicio, para todos los tenants. Las versiones son inmutables: un par de `service` y `version` que ya existe responde `FLK-0803`. Quien llama necesita el permiso `create` sobre el recurso `catalog`.

La fijación es por tenant. Publicar una versión no cambia nada para un tenant hasta que ese tenant la fija, así que una subida nueva nunca mueve un workflow en marcha a otra especificación. Flowker lee la versión que fijaste cuando informa los esquemas de los executors de ese servicio en el catálogo, así que Obtener un executor del catálogo describe la versión que elegiste.

Eliminar un documento

Comprueba qué se rompería

Listar los recursos que referencian un esquema OpenAPI devuelve dos grupos, providerConfigurations y workflows. Los dos están siempre presentes, y cada entrada lleva un id, un name y un status. Una entrada con estado activo bloquea el borrado; una inactiva solo avisa.

Elimínalo

Eliminar un esquema OpenAPI responde según lo que todavía referencia el documento:

Resultado	Lo que significa
`204 No Content`	Nada referenciaba el documento. Ya no está.
`200 OK`	Solo lo tenían referentes inactivos — un workflow en draft o inactivo, o una configuración de provider deshabilitada. El documento ya no está, y el cuerpo nombra a cada uno bajo `warnings` y `providerConfigurationWarnings`.
`409` con `FLK-0945`	Una configuración de provider activa vincula el documento. No se elimina nada, y el cuerpo lista las configuraciones de provider y los workflows que lo referencian.
`409` con `FLK-0936`	Un workflow activo referencia el documento desde un trigger de webhook. No se elimina nada.

Para levantar un bloqueo, deshabilita la configuración de provider con Deshabilitar configuración de provider, o mueve el workflow a draft con Mover el workflow a draft, y elimina el documento de nuevo.

Qué puede salir mal

Síntoma	Causa	Solución
La subida se rechaza aunque el archivo abre en tu editor.	El documento declara una versión `openapi` fuera de la serie 3.x, o no declara ninguna operación.	Revisa el campo `openapi` y el objeto `paths`, y súbelo de nuevo.
La llamada de creación informa que el id del esquema es desconocido.	El id pertenece a otro tenant, o el documento se eliminó.	Llama a Listar esquemas OpenAPI y toma el id de la respuesta.
El workflow se rechaza con `FLK-0150`.	El `providerConfigId` del node nombra una configuración que no existe, o una deshabilitada.	Confirma el UUID del node, y habilita la configuración con Habilitar configuración de provider.
El node falla sin llegar a tu servicio.	La operación no está en el documento, o no se resuelve ninguna URL base.	Compara `operation_path` y `operation_method` con la lista `operations` del Paso 2, y define `config.base_url` cuando el documento no declara ninguna entrada `servers`.
El servicio responde que falta un campo obligatorio.	Un `target` de mapeo no coincide con el esquema de solicitud de la operación.	Lee `inputSchema` en Derivar el esquema de una operación y escribe cada target exactamente como aparece allí.
No se llega al servicio y el paso informa una URL rechazada.	`allowedHosts` no cubre el host de destino.	Agrega el host a `allowedHosts` en la configuración de provider.

Código de error	Cuándo	Lo que significa
`FLK-0150`	Crear o activar el workflow	El `providerConfigId` del node nombra una configuración que no existe, o una que no está activa.
`FLK-0812`	Subida	Ya existe un documento con este `name` y esta `version`. Elige otra versión.
`FLK-0900`	Subida	El archivo no se analiza como documento OpenAPI 3.x, o no declara ninguna operación.
`FLK-0901`	Subida	El archivo pasa de 8 MiB.
`FLK-0811`	Lectura, derivación, borrado	El id del documento no se resuelve para tu tenant.
`FLK-0902`	Derivar el esquema de una operación	El documento no declara ninguna operación con esa ruta y ese método.
`FLK-0304`	Derivar el esquema de una operación	Falta el parámetro de consulta `path`, o falta `method` o no es un método HTTP.
`FLK-0946`	Crear o actualizar la configuración de provider	Falta `config.openapi_schema_id`, o no es un UUID.
`FLK-0947`	Crear o actualizar la configuración de provider, y en tiempo de ejecución	El documento referenciado no existe en tu tenant.
`FLK-0948`	Crear o actualizar la configuración de provider	El bloque `config.auth` está mal formado.
`FLK-0293`	Crear o actualizar la configuración de provider	Una entrada de `schemaBindings` está mal formada.
`FLK-0942`	Crear o actualizar la configuración de provider	Una entrada de `schemaBindings` nombra un documento que no existe en tu tenant.
`FLK-0943`	Crear o actualizar la configuración de provider	Una entrada de `schemaBindings` restringe a una operación que el documento no declara.
`FLK-0949`	Tiempo de ejecución	Ni `config.base_url` ni una entrada `servers` utilizable resuelven una URL base. El node falla sin llamar al servicio.
`FLK-0950`	Tiempo de ejecución	La operación vinculada no está en el documento, o un parámetro `path` no encontró valor. El node falla sin llamar al servicio.
`FLK-0945`	Eliminar el documento	Una configuración de provider activa lo vincula.
`FLK-0936`	Eliminar el documento	Un workflow activo lo referencia desde un trigger de webhook.
`FLK-0803`	Subir una versión de especificación	Ese par de servicio y versión ya está publicado. Las versiones son inmutables.
`FLK-0801`	Fijar una versión de especificación	La solicitud no trae el servicio o la versión.

Consulta la Lista de errores de Flowker para ver todos los códigos.

Qué sigue

Trabajar con los datos de la solicitud y de la respuesta

Mapea valores al cuerpo de la solicitud de la operación y lee su respuesta de vuelta.

Configurar un trigger de webhook

Valida un payload entrante contra una operación del mismo documento.

Guía de integración

Define la autenticación, los reintentos y el circuit breaker que comparte cada configuración de provider.

API de esquemas OpenAPI

Explora los endpoints del registro de esquemas.

Resumen

Guías

Console

Operaciones

Conectar tu propia API

Antes de empezar

Paso 1: Sube el documento OpenAPI

Por qué clave se identifica un documento almacenado

Paso 2: Consulta las operaciones que puedes llamar

Paso 3: Apunta una configuración de provider hacia el documento

Dónde va la credencial

Dónde se definen las listas de hosts permitidos

Vincula el documento

Paso 4: Direcciona una operación desde un node de workflow

Cómo se arma la solicitud

Paso 5: Ejecútalo y confirma que funcionó

Publicar una nueva versión de tu documento

Versiones de especificación de los servicios del catálogo

Eliminar un documento

Qué puede salir mal

Qué sigue

Trabajar con los datos de la solicitud y de la respuesta

Configurar un trigger de webhook

Guía de integración

API de esquemas OpenAPI

​Antes de empezar

​Paso 1: Sube el documento OpenAPI

​Por qué clave se identifica un documento almacenado

​Paso 2: Consulta las operaciones que puedes llamar

​Paso 3: Apunta una configuración de provider hacia el documento

​Dónde va la credencial

​Dónde se definen las listas de hosts permitidos

​Vincula el documento

​Paso 4: Direcciona una operación desde un node de workflow

​Cómo se arma la solicitud

​Paso 5: Ejecútalo y confirma que funcionó

​Publicar una nueva versión de tu documento

​Versiones de especificación de los servicios del catálogo

​Eliminar un documento

​Qué puede salir mal

​Qué sigue

Trabajar con los datos de la solicitud y de la respuesta

Configurar un trigger de webhook

Guía de integración

API de esquemas OpenAPI

Antes de empezar

Paso 1: Sube el documento OpenAPI

Por qué clave se identifica un documento almacenado

Paso 2: Consulta las operaciones que puedes llamar

Paso 3: Apunta una configuración de provider hacia el documento

Dónde va la credencial

Dónde se definen las listas de hosts permitidos

Vincula el documento

Paso 4: Direcciona una operación desde un node de workflow

Cómo se arma la solicitud

Paso 5: Ejecútalo y confirma que funcionó

Publicar una nueva versión de tu documento

Versiones de especificación de los servicios del catálogo

Eliminar un documento

Qué puede salir mal

Qué sigue