Acciones de API (OpenAPI)

Un asistente de IA puede llamar operaciones de las APIs del cliente (ERP, CRM, facturación, inventario) sin escribir código ni mapear cada endpoint a mano: la API se conecta una vez en Integraciones con su especificación OpenAPI 3 o Swagger 2.0, y cada asistente elige qué operaciones puede usar y cómo.

Cómo funciona en dos pasos

Centro › Recursos › Integraciones › Añadir integración › API HTTP. Nombre, URL base, cómo se autentica (sin autenticación, clave en una cabecera, usuario y clave Basic, o token Bearer) y, si la tienes, la URL del swagger.json / openapi.yaml. Al guardar se importa la especificación y se abre el panel Operaciones.
Asistente → Acciones → Acciones de API. Eliges la integración y la operación (solo las habilitadas en el hub), escribes cuándo debe usarla el modelo y decides si pide confirmación. Guardas y ya puedes probar en el playground.

Las claves quedan cifradas en el ambiente y nunca llegan al modelo: la llamada la hace Zoan Cloud con la autenticación de la integración.

Especificación y operaciones

En la tarjeta de la API, Operaciones abre un panel con cuatro pestañas:

Operaciones: lista agrupada por etiqueta, con buscador. Cada operación tiene un interruptor Habilitada / Deshabilitada a nivel de ambiente: lo que no está habilitado aquí no lo puede usar ningún asistente. Las de escritura (POST, PUT, PATCH, DELETE) llevan el chip escritura.
Especificación: importar o reimportar por URL, archivo o texto pegado. Swagger 2.0 se convierte a OpenAPI 3 automáticamente. Al reimportar se muestra el diff (nuevas, cambiadas, retiradas), se conserva qué estaba habilitado y las operaciones que desaparecen dejan de exponerse. Si la especificación publicada en la URL cambia, la tarjeta avisa «Cambió».
Probar: rellena los parámetros de una operación y llámala desde la nube. Sirve para comprobar la autenticación y ver la forma real de la respuesta antes de dársela a un asistente.
Manual: para APIs sin especificación, define una operación a mano (método, ruta con {parámetros}, resumen y un ejemplo de cuerpo JSON del que se infiere el esquema). Produce la misma estructura que la importación.

Lo que se guarda de la especificación es una versión normalizada y recortada: por operación, la ruta, los parámetros (ruta, query y cabeceras que no sean de seguridad), el cuerpo JSON y el esquema de la respuesta 2xx. Se descartan ejemplos, callbacks, multipart y extensiones. Límites: 500 operaciones, 40 parámetros por operación, 4 niveles de anidación, 8 MB de archivo.

La acción en el asistente

Cada acción es una herramienta del modelo llamada api_<integración>_<operación> cuyas entradas son los parámetros de la operación y las propiedades de primer nivel del cuerpo JSON, con sus tipos, enumeraciones y descripciones tal como vienen de la especificación. Por acción puedes ajustar:

Ajuste	Para qué
Descripción	Cuándo usarla. Si la dejas vacía se usa el resumen de la operación más `MÉTODO /ruta`.
Pedir confirmación	Gate de dos turnos: el asistente resume lo que va a hacer con los valores ya resueltos y ejecuta solo cuando el usuario confirma. Activado por defecto en las operaciones de escritura.
Valores fijos	Entradas que el modelo no elige (`centroAtencionOid=1`): se inyectan en cada llamada y desaparecen del esquema.
Parámetros ocultos	Opcionales que no aplican al caso de uso.
Respuesta	Ruta dentro de la respuesta (`data.items`), campos que ve el modelo y máximo de caracteres (6 000 por defecto). Las respuestas grandes se recortan con una nota para que el modelo pida filtros más precisos.

Sugerir instrucciones en Comportamiento añade al prompt un bloque «Cómo usar las acciones de API» con la lista de acciones y la regla de confirmar antes de escribir, para que el orden de llamadas quede en palabras del negocio y no en código.

El modelo recibe de cada llamada estado (código HTTP), datos (respuesta proyectada) y nota. Un error 4xx/5xx llega con el mensaje del cuerpo de la respuesta para que el asistente lo explique al usuario; un 401 o 403 marca además la integración como Reautorizar en el hub hasta que se actualicen las claves.

Límites y seguridad

30 segundos por llamada, 1 MB de respuesta, solo el host de la integración.
Sin destinos en redes privadas, salvo que la integración marque red privada alcanzable por VPN.
Cada llamada deja un evento de auditoría assistant.api_call (integración, operación, estado, duración, conversación). Los cuerpos no se guardan.
OAuth2 client credentials y la ejecución a través del Agent para APIs solo accesibles en la red del cliente llegan en una fase posterior.

Catálogos sobre una integración de API

Los catálogos HTTP de Conocimiento pueden elegir una integración de API en lugar de una credencial suelta: la URL puede ser una ruta relativa (/api/productos) y la autenticación se toma de la integración.