← Todos los artículos

BoothDock · Wiki

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 existen en Windows y, desde la versión 1.5.10, también en iPad, iPhone y Mac. La API local está disponible desde la versión 1.4.0 también en iPad, iPhone y Mac, y la exportación en tiempo real desde la versión 1.5.2.

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.

Sistema → Automatización: exportación en tiempo real, webhooks y API local
Sistema → Automatización: exportación en tiempo real, webhooks y API local

Configurar webhooks

Introduce una Dirección (URL), en Windows también un Programa, o ambos. En cada evento, la Box llama a todo lo que hayas introducido:

  • Programa (solo Windows) – 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.

En iPad, iPhone y Mac solo existe la dirección. Allí http:// solo funciona dentro de la red local (dirección IP o .local), así que Shelly, WLED y Tasmota en la wifi funcionan. Las direcciones en internet necesitan https://.

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.

Dirección propia por evento

Desde la versión 1.5.10 puedes dar además a cada evento su propia dirección en Dirección propia por evento (opcional), por ejemplo para un enchufe Shelly, WLED o Tasmota en la wifi que se active con la cuenta atrás o con la captura. Ejemplo para countdown_start: http://192.168.1.50/relay/0?turn=on.

La Box llama a esta dirección además del programa y la dirección de arriba, como un GET simple sin valores añadidos. La dirección anterior y los scripts existentes siguen funcionando sin cambios. countdown llega cada segundo; con file_upload la Box llama a la dirección propia una vez por sesión (la dirección general, como antes, una vez por archivo).

Eventos

EventoCuándoParámetros
session_startUn invitado inicia una sesión y el modo ya está fijado1: modo (PrintOnly, PrintAndGIF, OnlyGIF, SlowMoOr360, Video), 2: modo de BoothDock (photo, gif, boomerang, video, slowmo, ai)
countdown_startEmpieza la cuenta atrás1: segundos
countdownCada segundo de la cuenta atrás1: progreso en porcentaje (desde 0)
capture_startLa cuenta atrás ha terminado y empieza la captura–
file_downloadLa cámara ha guardado una foto1: nombre de archivo, 2: ruta completa
processing_startEmpieza el procesamientoun nombre de archivo por cada original de la cámara y, como último valor, el archivo de impresión (de momento vacío)
sharing_screenAparece la pantalla de resultado (una vez por sesión)–
printingSe envía una hoja a una impresora1: archivo (de momento vacío), 2: copias, 3: impresora
file_uploadUn archivo ha llegado al Hub (por cada archivo)1: ruta en la Box, 2: enlace de la galería, 3: tipo (print, photo, original, animation, boomerang, video), 4: álbum (nombre del evento)
lead_submittedUn invitado ha enviado el formulario Datos de invitados (formulario) (desde 1.5.0)– (las respuestas solo están en la exportación CSV)
session_endLa sesión termina: completada, cancelada, caducada o eliminada–

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

ComandoEfecto
start?mode=printInicia una sesión. Modos: print (foto), gif, boomerang, slowmo (360°; sin 360°, el boomerang), video, ai. Solo funciona desde la pantalla de inicio, solo con un modo habilitado y no con la Box bloqueada. Con plantilla, estilo y fondo: ver más abajo.
auswahl?mode=printDevuelve en Data lo que se puede elegir en este modo: vorlagen (Id y nombre; vacío si solo hay una plantilla habilitada – entonces está en vorgabeVorlage), hintergruende por plantilla y, en el modo ai, los stile (desde 1.5.13).
cancelCancela la sesión en curso y vuelve a la pantalla de inicio.
statusDevuelve en Data: modo invitado sí/no, pantalla actual, modo, bloqueada sí/no – desde 1.5.13 también sperrgrund (manuell o zeitfenster) y oeffnetUm.
print?count=1Vuelve a imprimir el último resultado (de 1 a 10 hojas). Los vídeos no se pueden imprimir.
lockscreen/showBloquea la Box con el mensaje «Un momento – enseguida seguimos.» o con tu propio texto e imagen (ver «Pantalla de bloqueo» más abajo). La esquina de administración sigue accesible. Desde 1.5.13 el bloqueo se mantiene también tras reiniciar la app.
lockscreen/exitLevanta el bloqueo – desde 1.5.13 también el bloqueo por franja horaria, hasta el siguiente cambio.
share/email?email=…Envía el último resultado por correo; requiere la vinculación con el Hub y la acción del resultado «Recibir por correo» (Sistema → Funcionamiento → Acciones del resultado (invitado); hasta la 1.4.0, el interruptor «Foto por correo (invitado)» en Diseño → Pantallas).
share/smsNo existe; la respuesta lo dice con sinceridad (IsSuccessful: false).
createtestevent?name=…Crea un evento de prueba y lo activa. Data contiene eventId y eventName. Sin nombre, se crea uno con la fecha. Solo fuera del modo invitado (desde 1.5.4).
deletetestevent?eventId=…Elimina un evento de prueba creado mediante la API; nunca otros eventos. Solo fuera del modo invitado (desde 1.5.4).
pingComprueba sin contraseña si la API está en marcha.

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

Iniciar una sesión con plantilla, estilo y fondo

Desde la versión 1.5.13, start recibe la elección directamente – la Box se salta entonces justo esas pantallas de selección:

  • vorlage=<Id> (o template=) – la plantilla, solo en el modo print (foto). Los Id los da auswahl?mode=print.
  • stil=<Id> (o style=) – el estilo de IA, solo en el modo ai.
  • hintergrund=<Id> (o background=) – el fondo del recorte, a juego con la plantilla.

Ejemplo: http://localhost:1500/api/start?mode=print&vorlage=hochzeit-gold&hintergrund=strand&password=TU-CONTRASEÑA

Un Id desconocido o que no encaja no inicia ninguna sesión: IsSuccessful es false y ErrorMessage indica el motivo. El consentimiento de privacidad y el formulario de datos de invitados los sigue mostrando la propia Box – se aplican al invitado que está delante de la Box y no se pueden adelantar a través de la API.

Pantalla de bloqueo

En Eventos → Pantalla de bloqueo (desde 1.5.13) defines qué muestra una Box bloqueada: tu propio texto, tu propia imagen y – con franja horaria – una gran cuenta atrás hasta la apertura.

  • Franja horaria por evento: Con Abre a las y Cierra a las la Box está bloqueada antes del inicio y después del final.
  • Desbloquear en el dispositivo: Si hay un PIN de operador configurado (Sistema → Protección), la pantalla de bloqueo muestra un pequeño candado. Quien conoce el PIN desbloquea la Box. Si se desbloquea antes del inicio, queda abierta hasta el final.
  • A distancia: En el Hub, bajo Cabinas, bloqueas y desbloqueas cada Box que lo admita (Studio desde 1.5.13). Lo mismo funciona a través de BoothDock Station y con lockscreen/show / lockscreen/exit.

Una sesión en curso no se interrumpe ni por el bloqueo desde el Hub ni por la franja horaria – la Box se bloquea en cuanto el invitado termina.

Exportación en tiempo real

En la misma pestaña: cada archivo terminado se guarda al instante en la propia Box (Copia local), también sin Hub, ordenado por evento y tipo (impresiones, originales, GIF, vídeos; cada tipo se puede desactivar). Esta copia nunca se borra automáticamente. En Memoria USB / segunda carpeta añades un segundo destino: Escribir automáticamente en la memoria USB escribe en cada memoria USB conectada y Recuperar archivos pendientes copia después lo que se creó sin memoria. También puedes indicar una Segunda carpeta fija (tiene prioridad), por ejemplo una carpeta en la nube (OneDrive, Dropbox). Si un invitado elimina su sesión en el fotomatón, las copias también desaparecen. En iPad y iPhone: En la app Archivos en «En mi iPad › BoothDock Studio › Export». En BoothDock Studio 1.5.3 y anteriores solo existe en su lugar la Carpeta de exportación.

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 (Windows). 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