Viswoo API'ye giriş

Viswoo API, bir işletmenin ekranlarını, içeriğini ve raporlarını kendi sistemlerinden (ERP, kampanya aracı, fiyat veritabanı) yönetmesini sağlar. Eklentilerden ayrıdır: eklenti ekranda çalışan bir uygulamadır, API ise sizin sunucunuzdan Viswoo hesabına yapılan isteklerdir.

API, müşterinin hesabında API erişimi eklentisi açıkken çalışır (V-Premium’a dahildir, diğer paketlerde eklentiler sayfasından açılır). Raporlar için ayrıca Raporlar eklentisi gerekir.

Adres

https://api.viswoo.com/api/ext/v1

Bütün istekler HTTPS’tir. Gövdeler JSON’dur, alan adları camelCase’tir; zamanlar UTC ISO 8601 (2026-11-01T09:30:00Z), tarihler yyyy-MM-dd, kimlikler UUID’dir. Enum değerleri küçük harfle başlayan metindir (landscape, ready).

Anahtar

Anahtarı panelde Eklentiler → API erişimi sayfasında hesap sahibi ya da yönetici açar. Anahtar vzk_ ile başlar ve yalnız açıldığında bir kez gösterilir; Viswoo yalnız özetini saklar. Anahtar kişiye değil işletmeye aittir: açan kişi ekipten ayrılsa da çalışır. Geçerlilik 90 gün, 1 yıl ya da süresizdir; panelden hemen iptal edilebilir.

Her istekte Authorization başlığında gönderin:

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

Anahtarı tarayıcıda ya da mobil uygulamada kullanmayın; yalnız sunucunuzda saklayın.

İzinler

Anahtar açılırken izinleri seçilir; her uç bir izin ister. Anahtara yalnız gereken izni verin.

İzin	Ne açar
screens:read	Şubeler, ekranlar, canlı durum, komut durumu, uygulama görüntüsü
screens:write	Ekran ayarları ve uzaktan komutlar (yenile, yeniden başlat, görüntü al…)
content:read	Medya, klasörler, playlistler, zamanlama kuralları, etki denemesi, acil duyurular
content:write	Medya yükleme, klasör, playlist ve zamanlama değişikliği, acil duyuru
reports:read	Oynatma ve çalışma süresi raporları (JSON ve CSV)
webhooks:manage	Webhook adresleri ve teslim kaydı

Anahtarla yapılan değişiklikler hesabın yöneticisi yapmış gibi hemen yayına çıkar (içerik onayı açık olsa da) ve denetim kaydına “API: <anahtar adı>” olarak yazılır.

Hatalar

Hata cevabı ProblemDetails biçimindedir ve makine okunur bir code taşır:

{ "status": 404, "title": "screen.not_found", "code": "screen.not_found" }

Durum	Anlam
400	İstek geçersiz; doğrulama hatasında errors alan başına kodları verir
401	api_key.invalid: anahtar yok, yanlış, süresi dolmuş ya da iptal edilmiş
402	subscription.suspended: hesap askıda; okuma serbest, yazma kapalı
403	api_key.scope_missing (izin yok) ya da feature.not_subscribed (eklenti kapalı)
404	Kayıt yok ya da başka bir işletmenin (varlığı belli edilmez)
409	Çakışma: ör. media.in_use, folder.name_taken, screen.no_device
429	request.rate_limited: hız sınırı aşıldı

Sayfalama

Listeler page (1’den başlar) ve pageSize (en çok 100, varsayılan 50) alır:

{ "items": [], "page": 1, "pageSize": 50, "total": 132 }

Sıra belirlidir; bir sonraki sayfayı page artırarak alın.

Sınırlar

Anahtar başına dakikada 120 istek. Aşılınca 429 döner; birkaç saniye bekleyip yeniden deneyin. Medya dosyaları API’den geçmez: yükleme süreli bir adrese doğrudan yapılır (hızlı başlangıç).

Sürüm

Yol v1’dir ve yalnız eklenerek değişir (yeni alan, yeni uç); bilinmeyen alanları yok sayın. Kıran bir değişiklik v2 olarak gelir, v1 en az 6 ay birlikte çalışır. Değişiklikler sürüm notlarında duyurulur.

Bütün uçlar ve şemalar API başvurusunda, olay bildirimleri webhooklar sayfasındadır.