API και ενσωματώσεις

Κάθε δωμάτιο διαθέτει HTTP API. Ξεκινήστε και σταματήστε χρονόμετρα, εμφανίστε μηνύματα, προσθέστε χρόνο και διαβάστε το rundown από ένα script, ένα σύστημα show control ή οτιδήποτε μπορεί να στείλει ένα web request. Ένα webhook ενημερώνει το σύστημά σας όταν ένα χρονόμετρο ξεκινά ή τελειώνει.

Ξεκινήστε

Το API χειρίζεται το ίδιο δωμάτιο με το δωμάτιο ελέγχου: μια κλήση από το εργαλείο σας εμφανίζεται σε κάθε οθόνη ταυτόχρονα.

Αιτήματα

Κάθε κλήση έχει τη μορφή https://cliqer.io/api/timer/v1/<room>/<action>. Λειτουργούν τα GET, POST, PUT και PATCH. Οι παράμετροι μπαίνουν στο query string ή σε σώμα 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 επιλέγει ένα χρονόμετρο με βάση το 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. Το παράθυρο των πέντε λεπτών είναι δική σας επιλογή· εμποδίζει την επανάληψη (replay) ενός παλιού αιτήματος.

Η παράδοση γίνεται με μία μόνο προσπάθεια και χρονικό όριο 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

Δεν υπάρχει module Companion ούτε plugin Stream Deck για τα δωμάτια του Cliqer Timer. Το module Generic HTTP του Bitfocus Companion μπορεί να καλέσει τις παραπάνω ενέργειες. Το χρονόμετρο της εφαρμογής υπολογιστή Cliqer διαθέτει δικό του REST API και υποστήριξη Stream Deck, δείτε Timer (υπολογιστής) και Χρονόμετρο Host.

Συχνές ερωτήσεις

Επόμενα βήματα