API e integraciones

Cada sala tiene una API HTTP. Inicia y detén temporizadores, muestra mensajes, añade tiempo y lee la escaleta desde un script, un sistema de control de show o cualquier cosa capaz de hacer una petición web. Un webhook avisa a tu sistema cuando un temporizador empieza o termina.

Primeros pasos

La API controla la misma sala que la sala de control: una llamada desde tu herramienta se ve en todas las pantallas a la vez.

Peticiones

Todas las llamadas son https://cliqer.io/api/timer/v1/<room>/<action>. Funcionan GET, POST, PUT y PATCH. Los parámetros van en la query string, o en un cuerpo JSON con POST, PUT y PATCH; si ambos traen uno, prevalece el cuerpo. Los guiones en el nombre de la acción también funcionan, así que add-time equivale a add_time. /api/timer/v0/ acepta las mismas llamadas.

Envía la clave de una de estas formas, que se comprueban en este orden:

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

Claves y permisos

La clave de API de tu cuenta puede hacerlo todo en las salas de las que eres propietario. Una sala también puede tener sus propias claves, cada una con algunos de estos tres permisos:

Una llamada que necesita un permiso que la clave no tiene recibe 401. El secreto de una clave de sala se muestra una sola vez, al crearla. Para usar la API necesitas que tu plan la incluya, consulta Planes y límites.

Acciones

timer_id elige un temporizador por su id; index lo elige por posición, contando desde 1. Si se envían ambos, prevalece timer_id. Omite los dos para actuar sobre el temporizador actual.

Las cantidades son 30s, 5m, 1h, 250ms o un número de segundos sin unidad. seconds sirve en lugar de amount, y un signo menos va hacia atrás. Los interruptores como on, autostart y replace interpretan 0, false, off y no como desactivado y cualquier otro valor como activado. Omite on en blackout para alternarlo.

Respuestas

Todas las respuestas son JSON: {"ok": true, "message": "<action>", "data": ...} si todo va bien, {"ok": false, "message": "...", "code": "..."} si falla.

Límite de frecuencia: 100 llamadas por minuto por clave; las llamadas sin clave se cuentan por dirección. Cada respuesta incluye RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset (segundos hasta que vuelve a empezar el minuto).

Webhooks

El cuerpo es {"event", "roomId", "timestamp", "payload"}. La cabecera x-cliqer-timestamp contiene la hora Unix en segundos, y x-cliqer-signature contiene sha256= seguido del HMAC-SHA256 en hexadecimal de <timestamp>.<body> con tu secreto como clave.

# 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 el cuerpo en bruto exactamente como llegó, antes de analizar el JSON. La ventana de cinco minutos la decides tú; evita que se reenvíe una petición antigua.

La entrega es un único intento con un tiempo de espera de 5 segundos. No se siguen redirecciones, y se descarta cualquier dirección que resuelva a una red privada. Si un evento perdido te importa, consulta get_status para ponerte al día.

Enlaces cortos

GET https://cliqer.io/api/timer/link/<code> convierte el código de un enlace corto en su sala: {"ok": true, "data": {"roomId", "link"}}, o 404 Link not found si el código es desconocido, se ha revocado o ha caducado, o si la contraseña es incorrecta. Para un enlace con contraseña, envíala en la cabecera x-link-password, nunca en la dirección.

Companion y Stream Deck

No existe un módulo de Companion ni un plugin de Stream Deck para las salas de Cliqer Timer. El módulo Generic HTTP de Bitfocus Companion puede llamar a las acciones anteriores. El temporizador propio de la app de escritorio de Cliqer tiene su API REST y compatibilidad con Stream Deck, consulta Timer (escritorio) y Timer en el host.

Preguntas frecuentes

Siguiente