API de control: manejar bots desde fuera (scripts e IA)

Tras este artículo podrás manejar FlowBotCommander desde fuera: desde PowerShell, desde un programa propio o desde un asistente de IA que inicia y detiene tus bots mediante «function calling». No hacen falta conocimientos de programación — los ejemplos de abajo se copian tal cual.

Qué es la API de control

La aplicación contiene un pequeño servidor HTTP. Funciona solo en tu equipo (dirección 127.0.0.1), está desactivado de forma predeterminada y no deja entrar a nadie sin tu token. A través de esta interfaz un script puede

• consultar el estado (en ejecución, en pausa, qué bot está cargado),
• seguir el registro,
• listar los bots de la carpeta de bots,
• cargar, iniciar, pausar y detener un bot.

Lo que a propósito no puede hacer: editar bots, definir variables o crear nodos — eso se queda en el editor. La tecla de pánico (Pausa) detiene el bot en cualquier momento, haga lo que haga la API.

Paso 1 — Activar y copiar el token

1. Abre el menú Herramientas → API de control….
2. Marca Activar la API de control (opt-in).
3. Deja el puerto (8765) o cámbialo si otro programa lo ocupa.
4. Pulsa Copiar junto al token — lo necesitarás enseguida. Nuevo crea un token nuevo; el antiguo deja de valer.
5. Aplicar. Abajo aparece «● En ejecución en http://127.0.0.1:8765» y el registro recibe una línea 🌐 con la dirección.

El ajuste queda guardado: al siguiente inicio de la aplicación, la API vuelve a funcionar hasta que quites la marca. El token se guarda cifrado en tu equipo — nunca dentro de un bot ni en nuestro servidor.

Paso 2 — Poner los bots en la carpeta de bots

La API lista y carga bots solo de la carpeta %AppData%\FlowBotCommander\bots. Para llegar: Win+R, escribe %AppData%\FlowBotCommander\bots, Intro (crea la carpeta la primera vez). Guarda allí tus bots con Archivo → Guardar como… — cada uno se llama nombre.bot.json.

Paso 3 — La primera petición

Abre PowerShell e inserta tu token:

$token = "TU-TOKEN-AQUI"
$h = @{ Authorization = "Bearer $token" }

Invoke-RestMethod http://127.0.0.1:8765/api/health              # funciona sin token
Invoke-RestMethod -Headers $h http://127.0.0.1:8765/api/status  # todo lo demás exige el token

La respuesta de /api/status tiene este aspecto:

{ "running": false, "paused": false, "nodeCount": 6, "logCount": 12, "loadedBot": "clicker-heroes-komplett.bot.json" }

Paso 4 — Cargar, iniciar, pausar y detener un bot

# ¿Qué bots hay?
Invoke-RestMethod -Headers $h http://127.0.0.1:8765/api/bots

# Cargar un bot — nombre con o sin .bot.json, basta una parte del nombre
Invoke-RestMethod -Headers $h -Method Post -ContentType "application/json" `
    -Body '{ "name": "clicker-heroes-komplett" }' http://127.0.0.1:8765/api/bot/load

# Iniciar
Invoke-RestMethod -Headers $h -Method Post http://127.0.0.1:8765/api/run

# Pausar y reanudar
Invoke-RestMethod -Headers $h -Method Post -ContentType "application/json" `
    -Body '{ "paused": true }'  http://127.0.0.1:8765/api/pause
Invoke-RestMethod -Headers $h -Method Post -ContentType "application/json" `
    -Body '{ "paused": false }' http://127.0.0.1:8765/api/pause

# Detener
Invoke-RestMethod -Headers $h -Method Post http://127.0.0.1:8765/api/stop

Cada acción responde { "ok": true, "message": "…" } o { "ok": false, "message": "motivo" } — por ejemplo «Läuft bereits.» (ya en ejecución) o «Bot 'xyz' nicht gefunden.» (bot no encontrado). Los mensajes están actualmente en alemán.

Seguir el registro

/api/logs?since=N devuelve las líneas del registro a partir de la línea N (0 = todas). Recuerda cuántas líneas has leído y pide desde ahí la próxima vez — así solo recibes lo nuevo:

$lineas = Invoke-RestMethod -Headers $h "http://127.0.0.1:8765/api/logs?since=0"
$lineas.Count       # p. ej. 12
Invoke-RestMethod -Headers $h "http://127.0.0.1:8765/api/logs?since=12"   # solo las líneas nuevas

Todos los endpoints de un vistazo

Conectar un asistente de IA

GET /api/tools/openai devuelve una lista de herramientas lista para usar en formato OpenAI («tools»). Describe cada función — get_status, get_logs, list_bots, load_bot, run_bot, stop_bot, pause_bot — de modo que un modelo de lenguaje las llame correctamente por sí mismo. El montaje habitual:

1. Tu script obtiene el manifiesto y se lo pasa al servicio de IA como herramientas.
2. Le escribes a la IA: «Inicia el bot clicker-heroes-komplett y avísame si aparece un error en el registro».
3. La IA responde con una llamada de herramienta (p. ej. run_bot); tu script ejecuta la petición HTTP correspondiente y devuelve el resultado.

La aplicación no llama por sí misma a ningún servicio de IA — el puente entre la IA y la API es tu script. Así tu token se queda en tu equipo.

Seguridad

• La API solo es accesible desde tu propio equipo. Otros dispositivos de la red no pueden entrar — es intencionado y no se puede cambiar.
• El token es como una contraseña: no lo compartas ni lo pongas en bots o capturas de pantalla. Ante la duda, pulsa Nuevo y Aplicar.
• Desactiva la API cuando no la necesites.
• Pausa siempre detiene el bot — incluso en mitad de una acción de la API.