API e integrazioni

Ogni stanza ha un'API HTTP. Avvia e ferma i timer, mostra messaggi, aggiungi tempo e leggi la scaletta da uno script, da un sistema di show control o da qualsiasi cosa in grado di effettuare una richiesta web. Un webhook avvisa il tuo sistema quando un timer parte o termina.

Per iniziare

L'API gestisce la stessa stanza della regia: una chiamata dal tuo strumento appare su tutti gli schermi contemporaneamente.

Richieste

Ogni chiamata è https://cliqer.io/api/timer/v1/<room>/<action>. Funzionano GET, POST, PUT e PATCH. I parametri vanno nella query string oppure in un body JSON con POST, PUT e PATCH; se sono presenti in entrambi, prevale il body. Funzionano anche i trattini nel nome dell'azione, quindi add-time equivale a add_time. /api/timer/v0/ accetta le stesse chiamate.

Invia la chiave in uno di questi modi, verificati in quest'ordine:

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

Chiavi e permessi

La chiave API del tuo account può fare tutto nelle stanze di tua proprietà. Una stanza può anche avere chiavi proprie, ognuna con alcuni dei tre permessi:

Una chiamata che richiede un permesso che la chiave non ha riceve 401. Il segreto di una chiave di stanza viene mostrato una sola volta, al momento della creazione. Per usare l'API è necessario che sia inclusa nel tuo piano, vedi Piani e limiti.

Azioni

timer_id sceglie un timer tramite il suo id; index lo sceglie in base alla posizione, contando da 1. Se li invii entrambi, prevale timer_id. Omettili entrambi per agire sul timer corrente.

Le quantità sono 30s, 5m, 1h, 250ms oppure un semplice numero di secondi. seconds funziona al posto di amount, e un segno meno va all'indietro. Gli interruttori come on, autostart e replace interpretano 0, false, off e no come disattivato e qualsiasi altro valore come attivato. Ometti on in blackout per alternarlo.

Risposte

Ogni risposta è in JSON: {"ok": true, "message": "<action>", "data": ...} in caso di successo, {"ok": false, "message": "...", "code": "..."} in caso di errore.

Limite di frequenza: 100 chiamate al minuto per chiave; le chiamate senza chiave vengono conteggiate per indirizzo. Ogni risposta include RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset (i secondi mancanti all'inizio del minuto successivo).

Webhook

Il body è {"event", "roomId", "timestamp", "payload"}. L'header x-cliqer-timestamp contiene l'ora Unix in secondi, e x-cliqer-signature contiene sha256= seguito dall'HMAC-SHA256 esadecimale di <timestamp>.<body> calcolato con il tuo segreto come chiave.

# 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)

Firma il body grezzo esattamente come è arrivato, prima di qualsiasi parsing JSON. La finestra di cinque minuti è una tua scelta; impedisce che una vecchia richiesta venga riutilizzata.

La consegna prevede un solo tentativo con un timeout di 5 secondi. I redirect non vengono seguiti, e un indirizzo che si risolve in una rete privata viene scartato. Se un evento perso è importante, leggi get_status per rimetterti in pari.

Link brevi

GET https://cliqer.io/api/timer/link/<code> converte il codice di un link breve nella sua stanza: {"ok": true, "data": {"roomId", "link"}}, oppure 404 Link not found per un codice sconosciuto, revocato o scaduto o per una password errata. Per un link con password, inviala nell'header x-link-password, mai nell'indirizzo.

Companion e Stream Deck

Non esiste un modulo Companion né un plugin Stream Deck per le stanze Cliqer Timer. Il modulo Generic HTTP di Bitfocus Companion può chiamare le azioni indicate sopra. Il timer integrato nell'app desktop Cliqer ha una propria API REST e il supporto per Stream Deck, vedi Timer (desktop) e Timer host.

Domande frequenti

Prossimi passi