API, documentație și chei API

Tot ce face panoul se poate face și din programele dumneavoastră, prin API-ul REST al serverului: canale (pornire, oprire, repornire, configurare), statistici în timp real, evenimente, audiență, clipuri, înregistrări programate, perete de monitorizare, utilizatori. Panoul însuși folosește același API.

Documentația și cheile API sunt în toate planurile. Cheile pe zone, legate de IP-uri și cu limită aleasă sunt în ediția Enterprise. Disponibil din Castreon 1.6.0.

Pagina API

Administrare → API (doar administratori) are două file:

• Chei API — cheile pentru integrări (sisteme de automatizare, NOC, scripturi);
• Documentație — referința completă a API-ului: fiecare operație cu metoda, calea, rolul minim, zona, parametrii, un exemplu de cerere și de răspuns și comanda curl gata de copiat.

Descarcă openapi.json dă documentul OpenAPI 3.1 — îl importați direct în Postman, Insomnia sau Swagger UI ori în generatoare de cod (Python, TypeScript, Go, C#). E generat din același tabel după care serverul verifică fiecare cerere, deci e mereu exact pentru versiunea instalată. Adresa lui: https://server:port/api/v1/openapi.json (cu o cheie API sau cu sesiunea panoului).

Autentificarea

Fiecare cerere trimite cheia în antet:

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

Exemplu — repornirea unui canal (cheie cu rol de operator sau cu zona „Control canale”):

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

Erorile au mereu forma {"error":{"code":"…","message":"…"}} — code e stabil (pentru programe), message e pentru oameni.

Chei API

Cheie API nouă → nume, acces, expirare. Cheia se arată o singură dată — copiați-o atunci; serverul păstrează doar o amprentă a ei.

• După rol (toate planurile): cheia are drepturile unui rol întreg — Vizualizare, Operator sau Administrator.
• Pe zone (Enterprise): cheia poate doar ce au zonele bifate — Monitorizare (starea în direct), Citire configurație, Control canale (pornire, oprire, repornire, comenzi de playout), Modificare configurație, Administrare. O cheie pentru un ecran NOC primește doar Monitorizare; un sistem de automatizare primește Control canale. Tot ce iese din zonele ei e refuzat cu 403 și codul scope, cu numele zonei care lipsește.
• IP-uri permise (Enterprise): cheia merge doar de la adresele sau rețelele date (ex. 10.20.0.0/24); din altă parte — 403 key_ip.
• Limita de cereri: fiecare cheie are o limită (implicit 600 pe minut; în Enterprise o alegeți). Peste ea serverul răspunde 429 cu Retry-After; fiecare răspuns are X-RateLimit-Limit și X-RateLimit-Remaining.

Tabelul arată pentru fiecare cheie ultima folosire, adresa IP și numărul de cereri.

Cheie nouă fără oprirea integrărilor

Cheie nouă pe o cheie existentă face alta, cu aceleași drepturi. Alegeți cât să mai meargă cea veche — 24 de ore, 7 zile sau deloc — ca să apucați să schimbați cheia în integrări fără întrerupere. Revocă oprește o cheie imediat.

Pentru suport

Fiecare răspuns are antetul X-Request-ID (puteți trimite și dumneavoastră unul, ca să legați cererile de jurnalele proprii). Dacă o cerere nu merge, trimiteți-l în tichet.

Evenimente în timp real și webhook-uri

• GET /api/v1/events e un flux Server-Sent Events cu starea canalelor, statisticile și schimbările de configurație.
• Notificările (vezi Notificări) pot trimite alertele la un webhook semnat; formatul lui e descris în documentul OpenAPI.

Sfaturi

• O cheie pe integrare, cu cât mai puține drepturi și, unde se poate, legată de IP-ul integrării.
• Schimbați periodic cheile cu Cheie nouă (cu suprapunere), nu le reutilizați între sisteme.
• Cheile vechi din Utilizatori → Tokenuri API (versiunile dinainte) merg neschimbat; acum se administrează din pagina API.