Webhooks y API

BoothDock Studio puede avisar a otros programas de cada paso de una sesión (Webhooks) y dejarse controlar por otros programas (API local). Encontrarás ambas cosas en el área de administración, bajo Sistema → Automatización.

En BoothDock Studio 1.4.0 y versiones anteriores, los webhooks todavía se llaman allí «Disparadores».

Los webhooks y la exportación en tiempo real solo existen en Windows. La API local está disponible desde la versión 1.4.0 también en iPad y iPhone.

Usos típicos: luces o DMX sincronizados con la cuenta atrás, un overlay para streaming, un contador en la entrada… o un Stream Deck como mando a distancia de la Box.

Configurar webhooks

Introduce un Programa, una Dirección (URL) o ambos. En cada evento, la Box llama a los dos:

• Programa – un .exe, .bat o .cmd. Llamada: programa <evento> <param1> <param2> …. Cada valor llega como argumento independiente, aunque contenga espacios. El programa se inicia sin ventana, en su propia carpeta. Para un script de PowerShell (.ps1), pon delante un pequeño .bat que lo inicie.
• Dirección (URL) – http o https, llamada por GET: https://tu-servidor/hook?event_type=<evento>&param1=…&param2=…. Los valores van codificados para URL; los parámetros que ya figuran en tu dirección se conservan.

La sesión nunca espera a tu webhook: el programa y la llamada se ejecutan en paralelo, y una llamada puede durar como máximo 5 segundos. Enviar prueba envía al instante un session_start; así compruebas la conexión sin iniciar una sesión.

El programa y la dirección solo se pueden configurar directamente en la Box, no a través del Hub: una ruta de programa equivale al derecho de ejecutar algo en el ordenador.

Eventos

Ejemplo de un .bat que registra cada evento: echo %DATE% %TIME% %* >> "%~dp0eventos.log"

API local

Otros programas controlan la Box por HTTP: por ejemplo, un Stream Deck, un script propio o un control 360° desde el móvil.

• Activar: Sistema → Automatización → Activar API. De fábrica, la API está desactivada. Puerto 1500, modificable.
• Dirección: http://localhost:1500/api/<comando> (o 127.0.0.1). De fábrica, la Box solo acepta peticiones de este ordenador.
• Contraseña: 16 caracteres, se muestra en la misma sección; puedes copiarla o generar una nueva. Se envía como ?password=…, como cabecera X-Api-Password o como Authorization: Bearer …. Solo ping funciona sin ella.
• Respuesta: siempre HTTP 200 con JSON, por ejemplo {"ApiVersion":1,"Command":"cancel","IsSuccessful":true,"ErrorMessage":""}. Si ha funcionado lo indica IsSuccessful; en caso de error, el motivo aparece en ErrorMessage. Algunos comandos devuelven además Data.

Una llamada completa: http://localhost:1500/api/start?mode=print&password=TU-CONTRASEÑA

Control desde la red (móvil, tableta, 360°)

Activa además Accesible también desde la red. Entonces la Box acepta peticiones de dispositivos de la misma red Wi-Fi/LAN, nunca desde Internet.

• Dirección para el móvil: aparece en la línea de estado, por ejemplo http://192.168.1.20:1500. El ejemplo de debajo muestra entonces directamente la dirección adecuada.
• Sin introducir la IP: la Box se anuncia sola en la red (mDNS/Bonjour, tipo de servicio _boothdock._tcp, nombre «BoothDock» más el nombre del equipo). Las apps que la buscan la encuentran automáticamente.
• Bloqueo: si un dispositivo envía una contraseña incorrecta diez veces en diez minutos, queda bloqueado durante 15 minutos. Este ordenador nunca se bloquea.
• Solo en tu propia red: la contraseña viaja por la red sin cifrar. Usa el modo de red solo en tu propia Wi-Fi protegida, no en la Wi-Fi abierta para invitados del lugar del evento.
• Firewall: la instalación crea la regla, solo para redes privadas. Si la línea de estado muestra un aviso del firewall, reinstala BoothDock Studio o permítelo en Windows en «Permitir una aplicación a través del firewall». Si Windows trata la Wi-Fi como pública, los dispositivos no pueden entrar: cambia el perfil a Privada en las propiedades de red.

Comandos

Si la Box no responde en 15 segundos, se devuelve IsSuccessful: false con una indicación.

Exportación en tiempo real

En la misma pestaña eliges una Carpeta de exportación: por ejemplo, una memoria USB o una carpeta en la nube (OneDrive, Dropbox). Cada archivo terminado llega allí al instante, ordenado por evento y tipo (impresiones, originales, GIF, vídeos; cada tipo se puede desactivar). Si la memoria USB falta un momento, la Box copia los archivos más tarde. Si un invitado elimina su sesión en el fotomatón, las copias también desaparecen.

Inicio con mando a distancia

En la misma pestaña asignas una tecla en Inicio con mando a distancia. Los punteros de presentación, pulsadores USB y pedales suelen enviar la barra espaciadora; viene preajustada. En Inicia eliges qué activa la tecla en la pantalla de inicio: Como al tocar (flujo normal) o directamente un modo, por ejemplo, el 360° en la plataforma. En BoothDock Studio 1.4.0 y versiones anteriores, la tecla solo existe para el 360°; consulta 360° / Cámara lenta.

Solución de problemas

• No pasa nada: ¿aparece algo en el registro? Los webhooks escriben en webhooks.log (hasta la 1.4.0: ausloeser.log) y la API en lokale-api.log, ambos en la carpeta %LocalAppData%\Boothdock Studio\logs. Las peticiones rechazadas (contraseña incorrecta, dispositivo ajeno) se anotan allí como máximo una vez por minuto.
• «Invalid password.»: vuelve a copiar la contraseña; después de Nueva contraseña, la anterior deja de ser válida.
• «The booth is not on the start screen …»: start solo funciona desde la pantalla de inicio. Primero cancel, luego start.
• «Too many failed attempts …»: el dispositivo ha enviado demasiadas veces una contraseña incorrecta. Espera 15 minutos y comprueba la contraseña.
• El móvil no llega a la Box, pero en el ordenador todo funciona: casi siempre es el Firewall de Windows o una Wi-Fi tratada como pública; consulta más arriba. La línea de estado avisa de ambos casos.

Próximos pasos

• Modos de captura
• Impresión