API et intégrations

Chaque salle dispose d'une API HTTP. Démarrez et arrêtez des minuteurs, affichez des messages, ajoutez du temps et lisez le déroulé depuis un script, un système de contrôle de spectacle ou tout outil capable d'envoyer une requête web. Un webhook prévient votre système quand un minuteur démarre ou se termine.

Bien démarrer

L'API pilote la même salle que la régie : un appel depuis votre outil s'affiche sur tous les écrans en même temps.

Requêtes

Chaque appel a la forme https://cliqer.io/api/timer/v1/<room>/<action>. GET, POST, PUT et PATCH fonctionnent tous. Les paramètres passent dans la query string, ou dans un corps JSON en POST, PUT et PATCH ; le corps l'emporte quand les deux en contiennent. Les tirets dans le nom de l'action fonctionnent aussi : add-time équivaut à add_time. /api/timer/v0/ accepte les mêmes appels.

Envoyez la clé de l'une des façons suivantes, vérifiées dans cet ordre :

curl -X POST https://cliqer.io/api/timer/v1/<room>/add_time \
  -H "Authorization: Bearer $CLIQER_KEY" \
  -H "content-type: application/json" \
  -d '{"timer_id": "<timer>", "amount": "2m"}'

const res = await fetch('https://cliqer.io/api/timer/v1/<room>/add_time', {
  method: 'POST',
  headers: { 'authorization': `Bearer ${process.env.CLIQER_KEY}`, 'content-type': 'application/json' },
  body: JSON.stringify({ timer_id: '<timer>', amount: '2m' }),
})
const { ok, message, data } = await res.json()

import os, requests

r = requests.post(
    "https://cliqer.io/api/timer/v1/<room>/add_time",
    headers={"Authorization": f"Bearer {os.environ['CLIQER_KEY']}"},
    json={"timer_id": "<timer>", "amount": "2m"},
)
print(r.json())

Clés et permissions

La clé API de votre compte peut tout faire sur les salles dont vous êtes propriétaire. Une salle peut aussi avoir ses propres clés, chacune disposant de tout ou partie de ces trois permissions :

Un appel qui requiert une permission que la clé n'a pas reçoit 401. Le secret d'une clé de salle n'est affiché qu'une seule fois, à sa création. Pour utiliser l'API, votre forfait doit l'inclure, voir Forfaits et limites.

Actions

timer_id désigne un minuteur par son id ; index le désigne par sa position, en comptant à partir de 1. Si les deux sont envoyés, timer_id l'emporte. Omettez les deux pour agir sur le minuteur en cours.

Les durées s'écrivent 30s, 5m, 1h, 250ms, ou sous forme d'un simple nombre de secondes. seconds peut remplacer amount, et un signe moins fait reculer. Les interrupteurs comme on, autostart et replace interprètent 0, false, off et no comme désactivé, et toute autre valeur comme activé. Omettez on dans blackout pour le basculer.

Réponses

Chaque réponse est en JSON : {"ok": true, "message": "<action>", "data": ...} en cas de succès, {"ok": false, "message": "...", "code": "..."} en cas d'échec.

Limite de débit : 100 appels par minute et par clé ; les appels sans clé sont comptés par adresse. Chaque réponse contient RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset (nombre de secondes avant le début de la minute suivante).

Webhooks

Le corps est {"event", "roomId", "timestamp", "payload"}. L'en-tête x-cliqer-timestamp contient l'heure Unix en secondes, et x-cliqer-signature contient sha256= suivi du HMAC-SHA256 en hexadécimal de <timestamp>.<body>, calculé avec votre secret.

# Recompute the signature of a saved body.
printf '%s.%s' "$TIMESTAMP" "$(cat body.json)" \
  | openssl dgst -sha256 -hmac "$WHSEC" -hex

import { createHmac, timingSafeEqual } from 'node:crypto'

export function verify(rawBody: string, timestamp: string, signature: string, secret: string) {
  const want = `sha256=${createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex')}`
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300
  return fresh && want.length === signature.length && timingSafeEqual(Buffer.from(want), Buffer.from(signature))
}

import hashlib, hmac, time

def verify(raw_body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    mac = hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256)
    fresh = abs(time.time() - int(timestamp)) < 300
    return fresh and hmac.compare_digest("sha256=" + mac.hexdigest(), signature)

Calculez la signature sur le corps brut, exactement tel qu'il a été reçu, avant toute analyse JSON. La fenêtre de cinq minutes est un choix qui vous appartient ; elle empêche de rejouer une ancienne requête.

La livraison se fait en une seule tentative, avec un délai d'expiration de 5 secondes. Les redirections ne sont pas suivies, et une adresse qui pointe vers un réseau privé est ignorée. Si un événement manqué a de l'importance, lisez get_status pour vous remettre à jour.

Liens courts

GET https://cliqer.io/api/timer/link/<code> convertit le code d'un lien court en sa salle : {"ok": true, "data": {"roomId", "link"}}, ou 404 Link not found pour un code inconnu, révoqué ou expiré, ou pour un mauvais mot de passe. Pour un lien protégé par mot de passe, envoyez celui-ci dans l'en-tête x-link-password, jamais dans l'adresse.

Companion et Stream Deck

Il n'existe pas de module Companion ni de plugin Stream Deck pour les salles Cliqer Timer. Le module Generic HTTP de Bitfocus Companion peut appeler les actions ci-dessus. Le minuteur intégré à l'application de bureau Cliqer dispose de sa propre API REST et de la prise en charge de Stream Deck, voir Timer (bureau) et Minuteur de l'hôte.

FAQ

Et ensuite