Usar la API HTTP

Controla Beam Bench desde cualquier cliente HTTP. Las mismas operaciones que la CLI, con facilidad de integración.

La API HTTP/WebSocket de Beam Bench es la misma interfaz con la que se comunica la CLI. Si necesitas usar Beam Bench en un entorno sin CLI (una aplicación web, un servidor de integración o una aplicación móvil), utiliza directamente la API HTTP.

Qué necesitas

Beam Bench instalado.
La API local activada en Editar → Configuración → General. Está desactivada de forma predeterminada.
Un cliente HTTP (curl, la biblioteca HTTP de tu lenguaje, Postman, etc.).

Comprobar que la API está habilitada

Los valores predeterminados de la compilación actual están configurados de forma deliberadamente restrictiva:

API local: desactivada.
Puerto de la API: 5900.
Permitir dispositivos de red: desactivado. Mientras esta opción permanezca desactivada, el servidor solo acepta conexiones desde este ordenador.

Abre la aplicación de escritorio, ve a Editar → Configuración → General y activa API local. Deja Permitir dispositivos de red desactivado para los scripts que se ejecuten en el mismo ordenador. Los ajustes surten efecto de inmediato.

Lee la página de la API HTTP antes de vincular el servidor a la red en una Wi-Fi compartida. La API no tiene autenticación y puede mover la máquina y accionar el láser.

URL base

http://localhost:5900/api/v1

(O utiliza la IP LAN de tu máquina en lugar de localhost cuando Permitir dispositivos de red esté activado.)

Pasos

1. Comprobar que la API está disponible

curl -s http://localhost:5900/api/v1/agent/capabilities | jq .

Devuelve el esquema de capacidades. (Sustituye 5900 por el puerto que hayas configurado si lo has cambiado.)

2. Inspeccionar el estado

curl -s http://localhost:5900/api/v1/agent/state | jq .

3. Abrir un proyecto

curl -s -X POST http://localhost:5900/api/v1/projects/open \
  -H 'Content-Type: application/json' \
  -d '{"path":"/abs/path/to/file.lzrproj"}'

4. Renderizar el diseño (sin interfaz gráfica)

curl -s -X POST http://localhost:5900/api/v1/design/render \
  -H 'Content-Type: application/json' \
  -d '{"format":"png","pixels_per_mm":4,"output_path":"/tmp/out.png"}'

5. Obtener el estado de la cámara

curl -s http://localhost:5900/api/v1/camera/state | jq .

6. Renderizar la superposición de cámara (requiere la aplicación)

curl -s -X POST http://localhost:5900/api/v1/camera/overlay/render \
  -H 'Content-Type: application/json' \
  -d '{"output_path":"/tmp/overlay.png","view":"fit","keep":true}'

Grupos de endpoints disponibles

Consulta la sección Referencia de la API (cuando esté disponible) para ver la interfaz completa. Los grupos principales son:

/agent: capacidades, estado y guía.
/camera: dispositivos, estado, captura, superposición (visualización, transformación y renderizado), calibración y alineación.
/design: descripción, renderizado y transacciones.
/projects: abrir, guardar, cerrar, capas, objetos, deshacer/rehacer e importar.
/export: svg, dxf, pdf, eps y ai.

Seguridad

El servidor de la API no tiene autenticación. Presupone que la red a la que está conectado es de confianza.

La vinculación exclusiva a localhost limita la exposición a la máquina local.
La vinculación a la red es una opción independiente que abre la API a cualquier persona de la misma LAN. Actívala únicamente en una red de confianza.

Comprobar que ha funcionado

curl agent/capabilities devuelve un JSON.
Una llamada de renderizado genera el archivo solicitado.