Hızlı başlangıç

Örneklerde anahtar VISWOO_KEY ortam değişkenindedir. Önce anahtarın çalıştığını görün:

curl https://api.viswoo.com/api/ext/v1/me -H "Authorization: Bearer $VISWOO_KEY"

{
  "tenant": { "id": "…", "name": "Köşe Kafe" },
  "key": { "id": "…", "name": "ERP", "scopes": ["screens:read"], "expiresAt": "2027-11-01T00:00:00Z" }
}

Ekranları listeleme

screens:read izni:

curl "https://api.viswoo.com/api/ext/v1/screens?online=false" -H "Authorization: Bearer $VISWOO_KEY"

const api = (path, init = {}) =>
  fetch(`https://api.viswoo.com/api/ext/v1${path}`, {
    ...init,
    headers: { Authorization: `Bearer ${process.env.VISWOO_KEY}`, 'Content-Type': 'application/json', ...init.headers },
  }).then(async (r) => (r.ok ? (r.status === 204 ? null : r.json()) : Promise.reject(await r.json())));

const { items } = await api('/screens?pageSize=100');
for (const screen of items) console.log(screen.name, screen.device?.online ? 'çevrimiçi' : 'çevrimdışı');

using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

var http = new HttpClient { BaseAddress = new Uri("https://api.viswoo.com/api/ext/v1/") };
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("VISWOO_KEY"));
var page = await http.GetFromJsonAsync<JsonElement>("screens?pageSize=100");

Medya yükleme

content:write izni. Dosya API’den geçmez; üç adımdır:

1. POST /media/uploads ile dosyanın adı, türü ve boyutu bildirilir; süreli (30 dk) bir yükleme adresi döner.
2. Dosya bu adrese, dönen headers ile PUT edilir.
3. POST /media/{id}/complete çağrılır; Viswoo dosyayı doğrular ve işler. Durum ready olunca playlistte kullanılabilir (media.processed webhook’u da gelir).

import { readFile, stat } from 'node:fs/promises';

const file = 'yaz-kampanyasi.jpg';
const { size } = await stat(file);
const upload = await api('/media/uploads', {
  method: 'POST',
  body: JSON.stringify({ fileName: file, contentType: 'image/jpeg', sizeBytes: size }),
});
await fetch(upload.uploadUrl, { method: 'PUT', headers: upload.headers, body: await readFile(file) });
await api(`/media/${upload.media.id}/complete`, { method: 'POST' });

let media;
do {
  await new Promise((r) => setTimeout(r, 2000));
  media = await api(`/media/${upload.media.id}`);
} while (media.status === 'processing');

Desteklenen türler, boyut sınırları ve depolama kotası paneldekiyle aynıdır (media.unsupported_type, media.too_large, media.storage_quota_exceeded).

Playlist kurma

Playlist tek istekte öğeleriyle açılır; güncelleme de bütün listeyi yazar (listede olmayan öğe silinir).

curl -X POST https://api.viswoo.com/api/ext/v1/playlists \
  -H "Authorization: Bearer $VISWOO_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Yaz kampanyası", "shuffle": false, "items": [
        { "mediaId": "MEDYA_ID", "durationSeconds": 8 },
        { "mediaId": "MEDYA_ID_2", "durationSeconds": 8, "validFrom": "2026-06-01", "validTo": "2026-08-31" } ] }'

Öğede mediaId, designId, widget ve pluginCode’dan tam olarak biri verilir. Ekranlarda oynayan playlist değişince ekranlar birkaç saniye içinde güncellenir.

Zamanlama

Kurallar bütün olarak yazılır; listedeki ilk kural en yüksek önceliktir. Kaydetmeden önce etkisini deneyin:

curl -X POST https://api.viswoo.com/api/ext/v1/schedule/impact \
  -H "Authorization: Bearer $VISWOO_KEY" -H "Content-Type: application/json" \
  -d '{ "rules": [ { "name": "Öğle menüsü", "playlistId": "PLAYLIST_ID", "days": [1,2,3,4,5], "start": "11:00", "end": "14:00" } ] }'

Cevap önümüzdeki 7 günde kaç ekranda oynayan playlistin değişeceğini (affectedScreens, changedHours) ve yayın saatinde boş kalacak anları (gaps) verir. Uygunsa aynı gövdeyi PUT /schedule ile kaydedin. Günler 0 = pazar … 6 = cumartesi; bitiş başlangıçtan önceyse kural gece yarısını aşar. Hedef all, screens (screenIds) ya da tag (tag) olur.

Uzaktan komut

screens:write izni. Ekranın kabul ettiği komutlar device.availableCommands alanındadır:

curl -X POST https://api.viswoo.com/api/ext/v1/screens/EKRAN_ID/commands \
  -H "Authorization: Bearer $VISWOO_KEY" -H "Content-Type: application/json" -d '{ "type": "refresh-manifest" }'

Cevap 202 ile komut kaydını döner. Sonuç cihazdan gelince GET /screens/{id}/commands/{commandId} durumu succeeded ya da failed olur; cihaz çevrimdışıysa komut süresi dolunca expired olur.

Acil duyuru

curl -X POST https://api.viswoo.com/api/ext/v1/alerts \
  -H "Authorization: Bearer $VISWOO_KEY" -H "Content-Type: application/json" \
  -d '{ "title": "Tahliye tatbikatı", "message": "Saat 15:00", "tone": "danger", "target": "all" }'

Duyuru seçilen ekranlarda hemen tam ekran görünür; endsAt verilmezse POST /alerts/{id}/end ile bitirilir. Hesap askıdayken de gönderilebilir.