← Tous les articles

BoothDock · Wiki

Webhooks et API

BoothDock Studio peut informer d'autres programmes de chaque étape d'une session (webhooks) et se laisser piloter par d'autres programmes (API locale). Tu trouves les deux dans la zone d'administration sous Système → Automatisation.

Dans BoothDock Studio 1.4.0 et les versions antérieures, les webhooks s'y appellent encore « Déclencheurs ».

Les webhooks existent sous Windows et, depuis la version 1.5.10, aussi sur iPad, iPhone et Mac. L'API locale est disponible depuis la version 1.4.0 aussi sur iPad, iPhone et Mac, l'export en temps réel depuis la version 1.5.2.

Usages typiques : lumière ou DMX synchronisés avec le compte à rebours, un overlay de stream, un compteur à l'entrée – ou un Stream Deck comme télécommande pour la Box.

Système → Automatisation : export en temps réel, webhooks et API locale
Système → Automatisation : export en temps réel, webhooks et API locale

Configurer les webhooks

Renseigne le champ Adresse (URL), sous Windows aussi le champ Programme – ou les deux. À chaque événement, la Box appelle tout ce qui est renseigné :

  • Programme (Windows uniquement) – un .exe, .bat ou .cmd. Appel : programme <événement> <param1> <param2> …. Chaque valeur arrive comme argument distinct, même si elle contient des espaces. Le programme démarre sans fenêtre, dans son propre dossier. Pour un script PowerShell (.ps1), passe par un petit .bat placé devant.
  • Adresse (URL) – http ou https, appelée en GET : https://ton-serveur/hook?event_type=<événement>&param1=…&param2=…. Les valeurs sont encodées pour l'URL ; les paramètres déjà présents dans ton adresse sont conservés.

Sur iPad, iPhone et Mac, il n'y a que l'adresse. Là, http:// ne fonctionne que dans le réseau local (adresse IP ou .local) – Shelly, WLED et Tasmota sur le Wi-Fi fonctionnent donc. Les adresses sur Internet nécessitent https://.

La session n'attend jamais ton webhook : programme et appel tournent en parallèle, et un appel peut durer au maximum 5 secondes. Envoyer un test envoie immédiatement un session_start – tu vérifies ainsi la connexion sans lancer de session.

Le programme et l'adresse se règlent uniquement directement sur la Box, pas via le Hub : un chemin de programme est un droit d'exécuter quelque chose sur l'ordinateur.

Adresse propre par événement

Depuis la version 1.5.10, sous Adresse propre par événement (facultatif), tu peux en plus donner à chaque événement sa propre adresse – par exemple pour une prise Shelly, WLED ou Tasmota sur le Wi-Fi qui s'allume au compte à rebours ou à la prise de vue. Exemple pour countdown_start : http://192.168.1.50/relay/0?turn=on.

La Box appelle cette adresse en plus du programme et de l'adresse ci-dessus, sous forme de simple GET sans valeurs ajoutées. L'adresse précédente et les scripts existants continuent de fonctionner sans changement. countdown arrive chaque seconde ; pour file_upload, la Box appelle l'adresse propre une fois par session (l'adresse générale toujours une fois par fichier).

Événements

ÉvénementQuandParamètres
session_startUn invité lance une session, le mode est fixé1 : mode (PrintOnly, PrintAndGIF, OnlyGIF, SlowMoOr360, Video), 2 : mode BoothDock (photo, gif, boomerang, video, slowmo, ai)
countdown_startLe compte à rebours commence1 : secondes
countdownChaque seconde du compte à rebours1 : progression en pourcentage (à partir de 0)
capture_startLe compte à rebours est terminé, la prise de vue commence–
file_downloadL'appareil a enregistré une photo1 : nom de fichier, 2 : chemin complet
processing_startLe traitement commenceun nom de fichier par original de l'appareil, en dernière valeur le fichier d'impression (vide pour l'instant)
sharing_screenL'écran de résultat s'affiche (une fois par session)–
printingUne feuille part vers une imprimante1 : fichier (vide pour l'instant), 2 : copies, 3 : imprimante
file_uploadUn fichier est arrivé dans le Hub (pour chaque fichier)1 : chemin sur la Box, 2 : lien de galerie, 3 : type (print, photo, original, animation, boomerang, video), 4 : album (nom de l'événement)
lead_submittedUn invité a envoyé le formulaire Données des invités (formulaire) (depuis 1.5.0)– (les réponses elles-mêmes figurent uniquement dans l'export CSV)
session_endLa session se termine – terminée, annulée, expirée ou supprimée–

Exemple de .bat qui consigne chaque événement : echo %DATE% %TIME% %* >> "%~dp0evenements.log"

API locale

D'autres programmes pilotent la Box via HTTP – par exemple un Stream Deck, ton propre script ou une commande 360° sur le téléphone.

  • Activer : Système → Automatisation → Activer l'API. Par défaut, l'API est désactivée. Port 1500, modifiable.
  • Adresse : http://localhost:1500/api/<commande> (ou 127.0.0.1). Par défaut, la Box n'accepte que les requêtes de cet ordinateur.
  • Mot de passe : 16 caractères, affiché dans la même section – copie-le ou génères-en un nouveau. À transmettre via ?password=…, via l'en-tête X-Api-Password ou via Authorization: Bearer …. Seul ping fonctionne sans.
  • Réponse : toujours HTTP 200 avec du JSON, par exemple {"ApiVersion":1,"Command":"cancel","IsSuccessful":true,"ErrorMessage":""}. IsSuccessful indique si cela a fonctionné, ErrorMessage donne la raison en cas d'erreur. Certaines commandes renvoient en plus Data.

Un appel complet : http://localhost:1500/api/start?mode=print&password=TON-MOT-DE-PASSE

Piloter depuis le réseau (téléphone, tablette, 360°)

Active en plus Accessible aussi depuis le réseau. La Box accepte alors les requêtes des appareils du même Wi-Fi/LAN – jamais depuis Internet.

  • Adresse pour le téléphone : elle figure dans la ligne d'état, par exemple http://192.168.1.20:1500. L'exemple en dessous affiche alors directement l'adresse correspondante.
  • Sans saisir d'IP : la Box s'annonce elle-même sur le réseau (mDNS/Bonjour, type de service _boothdock._tcp, nom « BoothDock » suivi du nom de l'ordinateur). Les applis qui la recherchent la trouvent automatiquement.
  • Blocage : si un appareil envoie dix fois un mauvais mot de passe en dix minutes, il est bloqué pendant 15 minutes. Cet ordinateur lui-même n'est jamais bloqué.
  • Uniquement sur ton propre réseau : le mot de passe circule en clair sur le réseau. N'utilise le mode réseau que sur ton propre Wi-Fi protégé – pas sur le Wi-Fi invités ouvert du lieu.
  • Pare-feu : l'installation crée l'autorisation, uniquement pour les réseaux privés. Si la ligne d'état affiche un avertissement du pare-feu, réinstalle BoothDock Studio ou autorise-le dans Windows sous « Autoriser une application via le pare-feu ». Si Windows considère le Wi-Fi comme public, les appareils ne peuvent pas entrer – passe le profil sur Privé dans les propriétés réseau.

Commandes

CommandeEffet
start?mode=printLance une session. Modes : print (photo), gif, boomerang, slowmo (360° ; sans 360°, le boomerang), video, ai. Fonctionne uniquement depuis l'écran d'accueil, uniquement avec un mode activé et pas quand la Box est verrouillée. Avec modèle, style et arrière-plan : voir plus bas.
auswahl?mode=printRenvoie dans Data ce qu'il y a à choisir pour ce mode : vorlagen (Id et nom ; vide si un seul modèle est activé – il figure alors dans vorgabeVorlage), hintergruende par modèle et, en mode ai, les stile (à partir de 1.5.13).
cancelAnnule la session en cours et revient à l'écran d'accueil.
statusRenvoie dans Data : mode invité activé/désactivé, écran actuel, mode, verrouillée oui/non – à partir de 1.5.13 aussi sperrgrund (manuell ou zeitfenster) et oeffnetUm.
print?count=1Réimprime le dernier résultat (1 à 10 feuilles). Les vidéos ne peuvent pas être imprimées.
lockscreen/showVerrouille la Box avec « Un instant – on revient tout de suite. » ou avec ton propre texte et ta propre image (voir « Écran de verrouillage » plus bas). Le coin admin reste accessible. À partir de 1.5.13, le verrouillage persiste aussi après un redémarrage de l'app.
lockscreen/exitLève le verrouillage – à partir de 1.5.13 aussi le verrouillage par plage horaire, jusqu'au prochain changement.
share/email?email=…Envoie le dernier résultat par e-mail – nécessite le couplage au Hub et l'action de résultat « Recevoir par e-mail » (Système → Fonctionnement → Actions du résultat (invité) ; jusqu'à la 1.4.0, l'interrupteur « Photo par e-mail (invité) » sous Design → Écrans).
share/smsN'existe pas ; la réponse le dit honnêtement (IsSuccessful: false).
createtestevent?name=…Crée un événement de test et l'active. Data contient eventId et eventName. Sans nom, il reçoit un nom avec la date. Uniquement hors du mode invité (depuis 1.5.4).
deletetestevent?eventId=…Supprime un événement de test créé via l'API – jamais d'autres événements. Uniquement hors du mode invité (depuis 1.5.4).
pingVérifie sans mot de passe si l'API fonctionne.

Si la Box ne répond pas dans les 15 secondes, tu reçois IsSuccessful: false avec une indication.

Lancer une session avec modèle, style et arrière-plan

À partir de la version 1.5.13, start reçoit directement le choix – la Box saute alors exactement ces écrans de sélection :

  • vorlage=<Id> (ou template=) – le modèle, uniquement en mode print (photo). Les Id sont fournis par auswahl?mode=print.
  • stil=<Id> (ou style=) – le style IA, uniquement en mode ai.
  • hintergrund=<Id> (ou background=) – l'arrière-plan du détourage, assorti au modèle.

Exemple : http://localhost:1500/api/start?mode=print&vorlage=hochzeit-gold&hintergrund=strand&password=TON-MOT-DE-PASSE

Un Id inconnu ou inadapté ne lance aucune session : IsSuccessful vaut false, ErrorMessage indique la raison. La Box continue d'afficher elle-même le consentement à la protection des données et le formulaire de données invités – ils concernent l'invité devant la Box et ne peuvent pas être anticipés via l'API.

Écran de verrouillage

Sous Événements → Écran de verrouillage (à partir de 1.5.13), tu définis ce qu'affiche une Box verrouillée : ton propre texte, ta propre image et – avec la plage horaire – un grand compte à rebours jusqu'à l'ouverture.

  • Plage horaire par événement : Avec Ouvre à et Ferme à, la Box est verrouillée avant le début et après la fin.
  • Déverrouiller sur l'appareil : Si un code PIN opérateur est configuré (Système → Protection), l'écran de verrouillage affiche un petit cadenas. Quiconque connaît le PIN déverrouille la Box. Déverrouillée avant le début, elle reste ouverte jusqu'à la fin.
  • À distance : Dans le Hub sous Bornes, tu verrouilles et déverrouilles chaque Box qui le permet (Studio à partir de 1.5.13). La même chose fonctionne via BoothDock Station et avec lockscreen/show / lockscreen/exit.

Ni le verrouillage depuis le Hub ni la plage horaire n'interrompent une session en cours – la Box se verrouille dès que l'invité a terminé.

Export en temps réel

Dans le même onglet : chaque fichier terminé est enregistré aussitôt sur la Box elle-même (Copie locale) – même sans Hub, trié par événement et par type (impressions, originaux, GIF, vidéos – désactivables séparément). Cette copie n'est jamais supprimée automatiquement. Sous Clé USB / second dossier, tu ajoutes une seconde destination : Écrire automatiquement sur la clé USB écrit sur chaque clé branchée, Rattraper les fichiers manqués rattrape ce qui a été créé sans clé. Tu peux aussi indiquer un Second dossier fixe (prioritaire), par exemple un dossier cloud (OneDrive, Dropbox). Si un invité supprime sa session sur la borne, les copies disparaissent aussi. Sur iPad et iPhone : Dans l’app Fichiers sous « Sur mon iPad › BoothDock Studio › Export ». Dans BoothDock Studio 1.5.3 et antérieur, il n'y a à la place que le Dossier d'export.

Démarrage par télécommande

Dans le même onglet, tu associes une touche sous Démarrage par télécommande. Les télécommandes de présentation, boutons USB et pédales envoient le plus souvent la barre d'espace ; elle est préréglée. Sous Démarre, tu choisis ce que la touche déclenche sur l'écran d'accueil : Comme un toucher (déroulement normal) ou directement un mode, par exemple le 360° sur la plateforme. Dans BoothDock Studio 1.4.0 et les versions antérieures, la touche n'existe que pour le 360°, voir 360° / Ralenti.

Dépannage

  • Rien ne se passe : y a-t-il quelque chose dans le journal ? Les webhooks écrivent dans webhooks.log (jusqu'à la 1.4.0: ausloeser.log), l'API dans lokale-api.log – tous deux dans le dossier %LocalAppData%\Boothdock Studio\logs (Windows). Les requêtes refusées (mauvais mot de passe, appareil inconnu) y figurent au maximum une fois par minute.
  • « Invalid password. » – recopie le mot de passe ; après Nouveau mot de passe, l'ancien n'est plus valable.
  • « The booth is not on the start screen … » – start ne fonctionne que depuis l'écran d'accueil. D'abord cancel, puis start.
  • « Too many failed attempts … » – l'appareil a envoyé trop souvent un mauvais mot de passe. Attends 15 minutes et vérifie le mot de passe.
  • Le téléphone n'atteint pas la Box, alors que tout fonctionne sur l'ordinateur : presque toujours le pare-feu Windows ou un Wi-Fi classé comme public – voir plus haut. La ligne d'état signale les deux cas.

Prochaines étapes