API ושילובים

לכל חדר יש HTTP API. אפשר להפעיל ולעצור טיימרים, להציג הודעות, להוסיף זמן ולקרוא את סדר ההופעה מסקריפט, ממערכת בקרת הופעה או מכל דבר שיכול לשלוח בקשת רשת. webhook מודיע למערכת שלכם כשטיימר מתחיל או מסתיים.

תחילת העבודה

ה-API מפעיל את אותו חדר כמו חדר הבקרה: קריאה מהכלי שלכם מופיעה בכל המסכים בבת אחת.

בקשות

כל קריאה היא https://cliqer.io/api/timer/v1/<room>/<action>. GET, POST, PUT ו-PATCH עובדים כולם. הפרמטרים נשלחים במחרוזת השאילתה, או בגוף JSON ב-POST, PUT ו-PATCH; כשיש ערך בשניהם, הגוף גובר. גם מקפים בשם הפעולה עובדים, כך ש-add-time הוא add_time. /api/timer/v0/ מקבל את אותן קריאות.

שולחים את המפתח באחת מהדרכים הבאות, שנבדקות לפי הסדר הזה:

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

מפתחות והרשאות

מפתח ה-API של החשבון שלכם יכול לעשות הכול בחדרים שבבעלותכם. לחדר יכולים להיות גם מפתחות משלו, ולכל אחד מהם חלק משלוש הרשאות:

קריאה שדורשת הרשאה שאין למפתח מקבלת 401. הסוד של מפתח חדר מוצג פעם אחת, כשהוא נוצר. כדי להשתמש ב-API בכלל, ה-API צריך להיות כלול בתוכנית שלכם, ראו תוכניות ומגבלות.

פעולות

timer_id בוחר טיימר לפי המזהה שלו; index בוחר אותו לפי מיקום, בספירה מ-1. כששניהם נשלחים, timer_id גובר. בלי אף אחד מהם, הפעולה חלה על הטיימר הנוכחי.

כמויות הן 30s, 5m, 1h, 250ms, או מספר שניות בלי יחידה. seconds עובד במקום amount, וסימן מינוס מזיז אחורה. מתגים כמו on, autostart ו-replace מפרשים 0, false, off ו-no ככבוי וכל ערך אחר כפועל. בלי on ב-blackout, ההאפלה מחליפה מצב.

תגובות

כל תשובה היא JSON: {"ok": true, "message": "<action>", "data": ...} בהצלחה, {"ok": false, "message": "...", "code": "..."} בכישלון.

מגבלת קצב: 100 קריאות בדקה לכל מפתח; קריאות בלי מפתח נספרות לפי כתובת. כל תשובה כוללת RateLimit-Limit, RateLimit-Remaining ו-RateLimit-Reset (מספר השניות עד שהדקה מתחילה מחדש).

Webhooks

הגוף הוא {"event", "roomId", "timestamp", "payload"}. הכותרת x-cliqer-timestamp מכילה את זמן Unix בשניות, ו-x-cliqer-signature מכילה sha256= ואחריו HMAC-SHA256 בהקסדצימלי של <timestamp>.<body>, עם הסוד שלכם כמפתח.

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

יש לחשב את החתימה על הגוף הגולמי בדיוק כפי שהגיע, לפני כל פענוח JSON. חלון חמש הדקות הוא לבחירתכם; הוא מונע שליחה חוזרת של בקשה ישנה.

המסירה היא ניסיון אחד עם זמן קצוב של 5 שניות. אין מעקב אחר הפניות, וכתובת שמתפרשת לרשת פרטית נדחית. אם אירוע שהוחמץ חשוב, אפשר לקרוא את get_status כדי להשלים את הפער.

קישורים מקוצרים

GET https://cliqer.io/api/timer/link/<code> ממיר קוד של קישור מקוצר לחדר שלו: {"ok": true, "data": {"roomId", "link"}}, או 404 Link not found עבור קוד לא מוכר, מבוטל או שפג תוקפו, או סיסמה שגויה. בקישור עם סיסמה, יש לשלוח אותה בכותרת x-link-password, אף פעם לא בכתובת.

Companion ו-Stream Deck

אין מודול Companion או פלאגין Stream Deck לחדרי Cliqer Timer. המודול Generic HTTP של Bitfocus Companion יכול לקרוא לפעולות שלמעלה. לטיימר של אפליקציית Cliqer לשולחן העבודה יש REST API משלו ותמיכה ב-Stream Deck, ראו Timer (שולחן עבודה) ו-טיימר המארח.

שאלות נפוצות

השלב הבא