Usar la API con una IA

Una IA puede usar Fluenta de dos formas. Las dos actúan como tú, con tu rol.

Un agente que hace llamadas HTTP

1. Crea un token de API en «Configuración» → «Tokens de API». Mira Autenticación.
2. Guárdalo en la configuración de secretos del agente, por ejemplo en una variable de entorno. No lo pegues en la conversación.
3. Apunta el agente a la documentación en texto:

Los dos archivos llms están en español. Cada página en inglés está en https://docs.fluenta.io/en/docs/errors.md, con el nombre de la página en lugar de errors.

Instrucciones para pegar

Pega esto en las instrucciones de sistema del agente:

Tienes acceso a la API de Fluenta por HTTP.

- Base: https://api.fluenta.io/v1/external
- En cada solicitud envía el encabezado
  Authorization: Bearer $FLUENTA_TOKEN
  El token está en la variable de entorno FLUENTA_TOKEN. Nunca lo escribas en
  una respuesta ni en un registro.
- Documentación: https://docs.fluenta.io/llms.txt es el índice y
  https://docs.fluenta.io/openapi.json tiene todas las operaciones.
- Empieza con GET /me y luego GET /organizations. De ahí salen los permisos
  del token y el organizationId de cada organización. Todas las demás rutas
  llevan el organizationId en la ruta: no hay organización por defecto.
- Un id sale siempre de una respuesta anterior. Nunca inventes uno.
- Los días son YYYY-MM-DD en el reloj de la planta, no en UTC. El campo today
  de GET /organizations/{organizationId} es el hoy de la planta.
- Un error es { statusCode, code, message }. Decide por code y muestra
  message a la persona tal como llega. No repitas una llamada rechazada sin
  cambiarla.
- Con un 429 RATE_LIMITED espera los segundos del encabezado Retry-After
  antes de reintentar.
- Cita las cifras como llegan. No las recalcules.
- No borres nada sin pedir la vista previa y recibir un sí explícito de la
  persona. Un cambio rechazado no cambió nada: no digas que se hizo.

«Conectar con IA»

Claude y ChatGPT se conectan por MCP, sin token. La dirección es:

https://app.fluenta.io/mcp

1. Abre «Configuración» → «Conectar con IA». Ahí están la «Dirección del conector» y los pasos para cada aplicación.
2. Pega la dirección en la aplicación: en Claude, como conector personalizado; en ChatGPT, como servidor MCP personalizado con autenticación OAuth.
3. La aplicación te trae a Fluenta. Revisa la solicitud y pulsa «Permitir».

Lo que conviene saber:

• Viene con el Plan Pro. Una prueba de Pro y una organización exenta también lo tienen. La conexión solo alcanza las organizaciones que lo tienen.
• Es OAuth. Tú apruebas la conexión en Fluenta con tu sesión del panel y eliges sus permisos: «Leer» siempre, «Gestionar el Programa» si lo activas.
• Ofrece 38 herramientas. 23 solo leen: tu identidad y tus organizaciones, la planta, los tableros, el Programa, el catálogo de referencias, los reportes, la «Actividad de conexiones» y las dos vistas previas de borrado. 15 cambian el Programa y el catálogo, y piden «Gestionar el Programa»; dos de ellas borran, y solo con la confirmación de su vista previa.
• Un token de API no sirve aquí. La dirección MCP solo acepta la conexión de la propia aplicación: rechaza un token de API como una credencial inválida.
• Las 23 rutas de lectura del 2026-11-12 no tienen herramienta MCP. Un agente las alcanza con un token de API y esta documentación. Mira el registro de cambios.

«Desconectar», en Configuración, termina la conexión de inmediato.

Seguridad

• Un token actúa como tú. Alcanza todas las organizaciones a las que perteneces, con el rol que tienes en cada una, leído en cada solicitud.
• Prefiere solo «Leer». Sin «Gestionar el Programa», toda escritura responde 403 INSUFFICIENT_SCOPE. Actívalo solo si el agente debe cambiar el Programa.
• Ponle «Vencimiento». Elige 30 días, 90 días o 1 año. Un token con «Nunca» sirve hasta que lo revoques.
• Un token por agente. Puedes tener hasta 10 tokens activos. Con uno por uso, revocas ese sin afectar a los demás.
• Revócalo al terminar. «Revocar» lo termina de inmediato.
• Una IA puede seguir instrucciones del texto que lee. Lo que el token puede hacer, ese texto se lo puede pedir. Es otra razón para dar solo «Leer».
• Cada cambio hecho por la API queda en la «Actividad de conexiones», y listActivity la responde.