API Anahtarları

API Anahtarları, Useroam paneline başka bir yazılımın (otomasyon aracı, kendi uygulamanız, raporlama ya da CRM sisteminiz) güvenli şekilde bağlanması için anahtar ürettiğiniz yerdir. Anahtar, Profilim ekranının API Anahtarları sekmesindedir.

Ne işe yarar?

Bir yazılım bu anahtarla panelde gördüğünüz raporların hemen hepsini otomatik çekebilir: 5651 imzalı loglar, hotspot kullanımı (bağlı misafir, tekil ziyaretçi, yoğun saatler), Bumerang kampanya sonuçları, anket cevapları, QR menü siparişleri, otel talepleri, görev/bakım/stok raporları, etkinlik katılımı ve retail raporları.

Her anahtar tek bir cihaza bağlıdır. Anahtar, üretildiği anda panelde seçili olan cihazın verisini görür; başka cihazın ya da başka müşterinin verisine erişemez. Birden fazla cihazınız varsa her cihaz için ayrı anahtar üretin.

Ne zaman kullanılır?

• Bilgi işlem ekibiniz 5651 loglarını kendi arşivine otomatik çekmek istediğinde.
• Raporları kendi raporlama sisteminize (Power BI, Excel, Google Sheets) aktarmak istediğinizde.
• n8n, Zapier gibi bir otomasyon aracını panele bağlarken.
• Bir entegratör ya da yazılımcı sizden "API anahtarı" istediğinde.

Böyle bir ihtiyacınız yoksa bu sekmeyi kullanmanız gerekmez.

Başlamadan önce

• Panelin üst kısmından anahtarı üreteceğiniz cihazı seçin. Anahtar o cihaza bağlanır.
• Anahtarı kullanacak sunucunun dış IP adresini öğrenin (yazılımcınız verir). Örnek: 203.0.113.10 ya da en fazla 256 adreslik bir ağ bloğu 203.0.113.0/24.
• Yazılımın hangi verilere ihtiyacı olduğunu öğrenin; yalnız onları açacaksınız.
• Anahtarı yalnız o cihazda tam yetkili kullanıcılar üretebilir. Yetkiniz kısıtlıysa sekmede "Bu cihaz için API anahtarı yönetme yetkiniz yok." yazar ve Yeni Anahtar düğmesi pasif olur; hesap yöneticinizden isteyin.

Adım adım

Adım 1: API Anahtarları sekmesini açın

Üst çubuktaki kişi simgesiyle Profilim'i açın ve API Anahtarları sekmesine geçin. Başlığın altında "Bu anahtarlar yalnız şu cihazın verisine erişir: cihaz adı" yazar; doğru cihazda olduğunuzu buradan kontrol edin. Hiç anahtar yoksa ortada "Henüz API anahtarınız yok." görünür. Sağdaki Yeni Anahtar düğmesine basın.

Adım 2: Etiket, IP, erişim ve süreyi seçip Oluştur'a basın

Yeni API Anahtarı penceresi açılır:

• Etiket *: anahtarın ne için olduğunu hatırlatacak ad. Örnek: Power BI raporları, Log arşivi. En fazla 120 karakter.
• IP Whitelist *: anahtarın kullanılabileceği IP adresleri. Her satıra bir IP ya da ağ bloğu yazın (virgülle ayırmak da olur). Ağ bloğu en fazla /24 (256 adres) olabilir; 0.0.0.0/0 gibi geniş bloklar kabul edilmez. Bu adresler dışından gelen istekler reddedilir.
• Neye erişebilsin? *: anahtarın okuyabileceği veriler. Yalnız gerekenleri işaretleyin:
  • 5651 imzalı loglar (varsayılan işaretli)
  • Hotspot kullanımı: bağlı misafirler, tekil ziyaretçi, yoğun saatler, giriş başarısı, Rapor Dışı Kullanıcılar
  • Bumerang kampanyaları, Anketler, QR Menü, Otel, Operasyon (restoran, görev, bakım, stok), Etkinlik, Retail ve kupon
  • Misafir listesi ve pazarlama izinleri: kişisel veri içerir (telefon, ad, e-posta). Varsayılan kapalıdır; yalnız gerçekten gerekiyorsa açın. Kapalıyken raporlardaki telefon ve adlar maskeli gelir (ör. 5307****73).
• Geçerlilik Süresi (gün): en fazla 365 gün (1 yıl). Süre dolunca anahtar kendiliğinden çalışmaz.

Sarı kutu uyarır: anahtar yalnız bir kez gösterilir. Oluştur'a basın.

Adım 3: Anahtarı hemen kopyalayın

Sekmenin üstünde yeşil Yeni API Anahtarı Oluşturuldu kutusu çıkar. Anahtar usr_ ile başlar. Kopyala'ya basın ve anahtarı yazılımcınıza güvenli bir yoldan iletin. Sayfayı yenilediğinizde kutu kaybolur ve anahtar bir daha gösterilmez.

Adım 4: Doküman bağlantısını yazılımcınıza verin

Başlığın altındaki API dokümanı (tüm uçlar) bağlantısı ya da Nasıl kullanılır? penceresindeki düğme, tüm uçların parametrelerini, gereken erişim türünü ve örnek yanıtları gösteren doküman sayfasını açar: panel.useroam.com/api/docs. Yazılımcınızın ihtiyaç duyduğu her şey oradadır; sayfada istekleri tarayıcıdan deneyebilir.

Kısaca kullanım:

1. Her istekte Authorization: Bearer usr_... başlığı gönderilir.
2. Önce GET https://panel.useroam.com/api/v1/devices.php çağrılır; dönen nasid değeri (şifreli bir metin, ör. OT37I3...) diğer tüm isteklerde nasid parametresi olarak kullanılır. Cihazın panelde gördüğünüz numarası çalışmaz.
3. Hazır raporların listesi için reports.php?nasid=..., bir raporu çalıştırmak için reports.php?nasid=...&key=gunluk_ziyaret_trendi&gun=30.

Uç	Ne verir	Gereken erişim
me.php, devices.php	Anahtarın bilgisi ve bağlı olduğu cihaz	Her anahtar
reports.php	70'i aşkın hazır rapor (her raporun kendi modülü)	Raporun modülü
logs.php	5651 imzalı log listesi ve indirme adresleri	5651 imzalı loglar
hotspot.php	Kullanım özeti ve günlük seri; Rapor Dışı Kullanıcılar raporu; g=radar ile paneldeki canlı Radar ekranı	Hotspot kullanımı
bumerang.php	Kampanyalar, sonuçlar, gönderimler; rapor= ile paneldeki 12 hazır rapor; g=komuta Pazarlama Komuta Merkezi; g=misafir360 Misafir 360 segmentleri	Bumerang kampanyaları
anket.php	Anketler, soru dağılımları, NPS, ham cevaplar	Anketler
menu.php, menu-report.php	Menü analitiği, siparişler, çağrılar, görüşler; g=rapor ile paneldeki Menü Raporu	QR Menü
otel.php, otel-report.php	Otel talepleri, hız paketi satışları; g=rapor ile paneldeki Otel Raporu	Otel
operasyon.php	Görev panosu, restoran talepleri, bakım, stok; g=rapor ile paneldeki Operasyon raporu	Operasyon
etkinlik.php	Etkinlikler, katılım raporu, katılımcılar	Etkinlik
retail-report.php, coupon-redeem.php	Retail raporu (g=rapor ile paneldeki Retail raporu), kupon doğrulama ve kullanma	Retail ve kupon
guests.php, consents.php, logout-users.php, delete-users.php	Misafir listesi, pazarlama izinleri, çıkış/silme talepleri	Misafir listesi ve pazarlama izinleri

Önemli notlar: istekler IP whitelist'inizdeki adreslerden gelmelidir; log indirme adresleri 5 dakika geçerlidir; anahtarın erişimi olmayan bir uca istek 403 scope_denied döner; tüm API kullanımı denetim kaydına işlenir.

Adım 5: Gereksiz ya da sızan anahtarı iptal edin

Listede aktif bir anahtarın satırının sonundaki kırmızı çarpı düğmesine (İptal Et) basın ve onaylayın. Satır gri İptal rozetiyle listenin altına iner ve o anahtarla yapılan istekler reddedilir. Cihazda tam yetkili her kullanıcı, kimin ürettiğine bakmaksızın o cihazın anahtarlarını iptal edebilir.

Anahtar listesi sütunları

Sütun	Ne gösterir
Etiket	Verdiğiniz ad.
Anahtar	Anahtarın ilk 12 karakteri. Tamamı bir daha gösterilmez.
IP Whitelist	İzin verilen adresler.
Erişim	Anahtarın okuyabildiği veriler (ör. 5651 imzalı loglar, QR Menü).
Oluşturan	Anahtarı üreten kullanıcı.
Oluşturulma / Bitiş	Üretim zamanı ve son geçerlilik günü.
Son Kullanım	En son kullanıldığı zaman ve IP; hiç kullanılmadıysa çizgi.
Kullanım	Toplam istek sayısı.
Durum	Aktif (yeşil), Süresi Dolmuş (sarı) ya da İptal (gri).

Liste, o an seçili cihazın tüm anahtarlarını gösterir.

Uyarı ve hata mesajları

Mesaj	Ne yapmalısınız
Bu cihaz için API anahtarı yönetme yetkiniz yok.	Hesap yöneticinizden anahtar üretmesini isteyin.
En az bir erişim türü seçin.	"Neye erişebilsin?" altından en az bir kutu işaretleyin.
Etiket zorunludur (max 120 karakter).	Kısa bir ad yazın.
IP whitelist boş olamaz.	En az bir IP adresi yazın.
Geçersiz IP: ...	Adresi 203.0.113.10 gibi yazın.
Geçersiz ya da çok geniş IP bloğu (en fazla /24): ...	Bloğu 203.0.113.0/24 ya da daha dar yazın; daha geniş bloklar güvenlik için kabul edilmez.
Geçerlilik süresi 1-365 gün aralığında olmalıdır.	1 ile 365 arasında bir sayı yazın.
API anahtarı iptal edildi.	İptal başarılı.

Sık sorulanlar

Anahtarı kopyalamayı unuttum. Tekrar gösterilemez. Eski anahtarı iptal edip yenisini oluşturun.

Birden fazla cihazımın verisini tek anahtarla çekebilir miyim? Hayır. Güvenlik için her anahtar tek cihaza bağlıdır; her cihaz için ayrı anahtar üretin.

Raporlarda telefonlar yıldızlı geliyor. Anahtarda "Misafir listesi ve pazarlama izinleri" kapalı. Gerçekten gerekiyorsa bu erişimle yeni bir anahtar üretin.

Paneldeki raporların aynısını API'den alabilir miyim? Evet. API, paneldeki raporla aynı hesaplamayı kullanır; sonuç birebir aynıdır. Bumerang: bumerang.php?rapor=ozet (diğer tipler: kampanya, tiklayan, donus, misafir, menu, urun, anket, cagri, otel, izinli, otel_ariza). Otel: otel.php?g=rapor&r=ozet (tip, personel, oda, sla, gelir). Operasyon: operasyon.php?g=rapor. QR Menü: menu.php?g=rapor. Pazarlama Komuta Merkezi: bumerang.php?g=komuta. Misafir 360: bumerang.php?g=misafir360 (segment için sf=sadik gibi, sayfa için sy=2; adla ya da telefonla arama q= misafir erişimi ister). Radar: hotspot.php?g=radar. Retail: retail-report.php?g=rapor. Paneldeki filtreler (tarih, kanal, personel, oda gibi) aynı adla çalışır. İngilizce başlıklar için &lang=en ekleyin. Bumerang raporlarında telefon ve adlar, panelde olduğu gibi, misafir erişimi açık olsa da maskelidir.

Süresi dolan anahtarı uzatabilir miyim? Hayır. Yeni anahtar oluşturup yazılımınızda değiştirin.

Cihazı başka bir hesaba taşıdık. O cihaz için üretilmiş anahtarlar kendiliğinden çalışmaz hale gelir; yeni hesapta yeni anahtar üretin.

İlgili sayfalar

• Profilim (Hesap Bilgileri)
• 5651 Logları
• İşlem Kayıtları