API i integracje

Każdy pokój ma API HTTP. Uruchamiaj i zatrzymuj timery, wyświetlaj wiadomości, dodawaj czas i odczytuj harmonogram ze skryptu, systemu sterowania show lub z czegokolwiek, co potrafi wysłać żądanie HTTP. Webhook informuje Twój system, gdy timer startuje lub się kończy.

Pierwsze kroki

API steruje tym samym pokojem co panel sterowania: wywołanie z Twojego narzędzia pojawia się od razu na każdym ekranie.

Żądania

Każde wywołanie ma postać https://cliqer.io/api/timer/v1/<room>/<action>. Działają GET, POST, PUT i PATCH. Parametry podajesz w query stringu albo w treści JSON przy POST, PUT i PATCH; gdy parametr jest w obu miejscach, pierwszeństwo ma treść. Myślniki w nazwie akcji też działają, więc add-time to add_time. /api/timer/v0/ przyjmuje te same wywołania.

Wyślij klucz w jeden z poniższych sposobów, sprawdzanych w tej kolejności:

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

Klucze i uprawnienia

Klucz API Twojego konta może wszystko w pokojach, których jesteś właścicielem. Pokój może mieć też własne klucze, a każdy z nich ma wybrane spośród trzech uprawnień:

Wywołanie wymagające uprawnienia, którego klucz nie ma, otrzymuje 401. Sekret klucza pokoju jest wyświetlany tylko raz, przy jego tworzeniu. Aby w ogóle korzystać z API, Twój plan musi je obejmować, zobacz Plany i limity.

Akcje

timer_id wybiera timer po identyfikatorze; index wybiera go po pozycji, licząc od 1. Gdy wysłane są oba, wygrywa timer_id. Pomiń oba, aby działać na bieżącym timerze.

Wartości czasu to 30s, 5m, 1h, 250ms lub sama liczba sekund. Zamiast amount działa też seconds, a znak minus cofa czas. Przełączniki takie jak on, autostart i replace traktują 0, false, off i no jako wyłączone, a wszystko inne jako włączone. Pomiń on w blackout, aby go przełączyć.

Odpowiedzi

Każda odpowiedź to JSON: {"ok": true, "message": "<action>", "data": ...} w razie powodzenia, {"ok": false, "message": "...", "code": "..."} w razie błędu.

Limit żądań: 100 wywołań na minutę na klucz; wywołania bez klucza liczone są na adres. Każda odpowiedź zawiera RateLimit-Limit, RateLimit-Remaining i RateLimit-Reset (liczbę sekund do rozpoczęcia kolejnej minuty).

Webhooki

Treść ma postać {"event", "roomId", "timestamp", "payload"}. Nagłówek x-cliqer-timestamp zawiera czas uniksowy w sekundach, a x-cliqer-signature zawiera sha256= i szesnastkowy HMAC-SHA256 z <timestamp>.<body>, obliczony z Twoim sekretem jako kluczem.

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

Obliczaj podpis z surowej treści dokładnie w takiej postaci, w jakiej dotarła, przed jakimkolwiek parsowaniem JSON. Pięciominutowe okno to Twój wybór; chroni przed ponownym odtworzeniem starego żądania.

Dostarczenie to jedna próba z 5-sekundowym limitem czasu. Przekierowania nie są obsługiwane, a adres wskazujący na sieć prywatną jest odrzucany. Jeśli pominięte zdarzenie ma znaczenie, odczytaj get_status, aby nadrobić zaległości.

Krótkie linki

GET https://cliqer.io/api/timer/link/<code> zamienia kod krótkiego linku na jego pokój: {"ok": true, "data": {"roomId", "link"}} albo 404 Link not found w przypadku nieznanego, unieważnionego lub wygasłego kodu albo błędnego hasła. Hasło do linku wysyłaj w nagłówku x-link-password, nigdy w adresie.

Companion i Stream Deck

Nie ma modułu Companion ani wtyczki Stream Deck dla pokoi Cliqer Timer. Moduł Generic HTTP w Bitfocus Companion może wywoływać powyższe akcje. Własny timer aplikacji desktopowej Cliqer ma swoje REST API i obsługę Stream Deck, zobacz Timer (aplikacja desktopowa) i Timer hosta.

Najczęstsze pytania

Co dalej