API, documentación y claves de API

Todo lo que hace el panel también se puede hacer desde tu propio software mediante la API REST del servidor: canales (inicio, parada, reinicio, configuración), estadísticas en tiempo real, eventos, audiencia, clips, grabaciones programadas, pared de monitorización, usuarios. El propio panel usa la misma API.

La documentación y las claves de API están en todos los planes. Las claves por ámbitos, vinculadas a IP y con límite propio forman parte de la edición Enterprise. Disponible desde Castreon 1.6.0.

La página API

Administración → API (solo administradores) tiene dos pestañas:

• Claves de API — las claves para integraciones (sistemas de automatización, herramientas NOC, scripts);
• Documentación — la referencia completa de la API: cada operación con su método, ruta, rol mínimo, ámbito, parámetros, un ejemplo de petición y de respuesta y el comando curl listo para copiar.

Descargar openapi.json da el documento OpenAPI 3.1: impórtalo directamente en Postman, Insomnia o Swagger UI, o en generadores de código (Python, TypeScript, Go, C#). Se genera a partir de la misma tabla con la que el servidor comprueba cada petición, así que siempre coincide con la versión instalada. Su dirección: https://servidor:puerto/api/v1/openapi.json (con una clave de API o con la sesión del panel).

Autenticación

Cada petición envía la clave en una cabecera:

curl -H 'Authorization: Bearer cst_…' https://servidor:33443/api/v1/channels

Ejemplo — reiniciar un canal (clave con rol de operador o con el ámbito «Control de canales»):

curl -X POST -H 'Authorization: Bearer cst_…' https://servidor:33443/api/v1/channels/<id>/restart

Los errores siempre tienen la forma {"error":{"code":"…","message":"…"}}: code es estable (para programas), message es para personas.

Claves de API

Nueva clave de API → nombre, acceso, caducidad. La clave se muestra una sola vez: cópiala en ese momento; el servidor solo guarda una huella.

• Por rol (todos los planes): la clave tiene los derechos de un rol completo — Visualización, Operador o Administrador.
• Por ámbitos (Enterprise): la clave solo puede hacer lo que permiten los ámbitos marcados — Monitorización (estado en directo), Lectura de configuración, Control de canales (inicio, parada, reinicio, órdenes de playout), Cambio de configuración, Administración. Una clave para una pantalla NOC recibe solo Monitorización; un sistema de automatización recibe Control de canales. Todo lo que queda fuera de sus ámbitos se rechaza con 403 y el código scope, indicando el ámbito que falta.
• IP permitidas (Enterprise): la clave solo funciona desde las direcciones o redes indicadas (p. ej. 10.20.0.0/24); desde otro sitio — 403 key_ip.
• Límite de peticiones: cada clave tiene un límite (600 por minuto por defecto; en Enterprise lo eliges tú). Por encima, el servidor responde 429 con Retry-After; cada respuesta lleva X-RateLimit-Limit y X-RateLimit-Remaining.

La tabla muestra para cada clave el último uso, la dirección IP y el número de peticiones.

Una clave nueva sin detener las integraciones

Renovar en una clave existente crea otra con los mismos derechos. Elige cuánto tiempo sigue funcionando la anterior — 24 horas, 7 días o nada — para cambiar la clave en tus integraciones sin interrupciones. Revocar detiene una clave al instante.

Para el soporte

Cada respuesta tiene la cabecera X-Request-ID (también puedes enviar la tuya, para enlazar las peticiones con tus registros). Si una petición falla, inclúyela en el ticket.

Eventos en tiempo real y webhooks

• GET /api/v1/events es un flujo Server-Sent Events con el estado de los canales, las estadísticas y los cambios de configuración.
• Las notificaciones (consulta Notificaciones) pueden enviar las alertas a un webhook firmado; su formato se describe en el documento OpenAPI.

Consejos

• Una clave por integración, con los menos derechos posibles y, cuando se pueda, vinculada a la IP de la integración.
• Cambia las claves periódicamente con Renovar (con solapamiento) y no las reutilices entre sistemas.
• Las claves anteriores de Usuarios → Tokens de API (versiones previas) siguen funcionando; ahora se gestionan en la página API.