Rapor24 REST API ve Entegrasyon
REST API ve webhook ile Rapor24 verisini kendi sistemlerinizle bütünleştirin. Power BI, Tableau, özel pano, ERP, CRM — hangi sistemi kullanırsanız kullanın, veri akışı standartlaştırılmıştır.
API Belgeleri Özeti
Rapor24 REST API, OpenAPI 3.0 standardında belgelenmiştir. Tüm uç noktalar JSON biçiminde veri döndürür; TLS 1.3 üzerinden HTTPS zorunludur ve kimlik doğrulama API anahtarıyla yapılır.
Ana uç nokta grupları:
/api/v1/counts: Ziyaretçi sayımı verisi/api/v1/heatmap: Bölge bazlı yoğunluk (ısı) haritası/api/v1/conversion: Dönüşüm oranı (POS entegrasyonu varsa)/api/v1/occupancy: Anlık doluluk/api/v1/forecasts: Tahmin verisi/api/v1/locations: Şube / sayım noktası üst verisi
Her uç nokta; zaman aralığı, ayrıntı düzeyi ve konum süzgeci gibi parametreleri destekler.
Uç Nokta Örnekleri
Saatlik ziyaretçi sayımı:
GET /api/v1/counts?location=istanbul-1&from=2026-05-01&to=2026-05-31&granularity=hour
Döndürür: saat saat ziyaretçi sayısı dizisi.
Anlık doluluk:
GET /api/v1/occupancy?location=istanbul-1
Döndürür: o anda içerideki kişi sayısı + kapasite yüzdesi.
Çoklu konum toplu çekim:
POST /api/v1/counts/bulk
{ "locations": ["istanbul-1", "istanbul-2"], "from": "...", "to": "..." }
Webhook Desteği
Çekme (pull) yönteminin yanında, anlık (push) webhook desteği vardır. Belirli olaylar tetiklendiğinde sistem, önceden tanımladığınız adrese bir POST isteği gönderir.
Desteklenen webhook tipleri:
- Doluluk eşiği aşımı: Kapasite %X üzeri
- Kuyruk uyarısı: Bekleyen kişi sayısı eşiği aşımı
- Saatlik özet: Her saat başı standart rapor
- Günlük özet: Gün sonu raporu
- Anomali uyarısı: Beklenen ve gerçek trafik arasında belirgin sapma
- Kamera arızası: Sayım noktasının bağlantısı kesildi
Webhook gövdesi JSON biçimindedir; HMAC SHA256 imzasıyla doğrulanır.
İstek Sınırları
API istek sınırları:
| Katman | Dakikalık | Günlük |
|---|---|---|
| Standart | 60 istek | 10.000 istek |
| Pro | 600 istek | 500.000 istek |
| Kurumsal | Özel | Özel |
Sınır aşımında 429 (Too Many Requests) yanıtı ve Retry-After başlığı döner.
Hazır Entegrasyonlar
Yaygın iş zekâsı, ERP/POS ve bildirim sistemleri için hazır bağlayıcılarımız vardır. Desteklenmeyen sistemler için REST API + webhook ile özel entegrasyon yapılabilir.
Veri görselleştirme
- Microsoft Power BI (hazır bağlayıcı)
- Tableau (Web Data Connector)
- Looker / Looker Studio
- Grafana
ERP / POS
- Logo Tiger / Wings
- Netsis
- SAP Retail / S/4HANA
- Mikro Yazılım
- ETA
Bildirim ve iletişim
- Slack
- Microsoft Teams
- Twilio (SMS)
İş gücü yönetimi
- Logo İK
- SAP SuccessFactors
- BambooHR
Bilet / sıramatik
- Q-matic
- Wavetec
- Esatto
Entegrasyon Mimarisi ve En İyi Uygulamalar
Rapor24 REST API'si modern entegrasyon desenlerini izler; böylece BI, ERP ve POS akışlarınız hem gerçek zamanlı hem güvenilir olur.
- Push mı, pull mu? Gerçek zamanlı ihtiyaçlar (canlı panolar, doluluk/eşik uyarıları) için webhook kullanın — anlık iletir ve hız limitini tüketmez. BI/veri ambarı eşitlemeleri için zamanlanmış çekme (ör. saatlik/gecelik) idealdir; küçük bir güvenlik amaçlı çekme, kaçan webhook'ları yakalar.
- Güvenli webhook'lar: Her webhook HMAC-SHA256 ile imzalanır; gövdeyi işlemeden önce imzayı doğrulayın, ~5 dakikadan eski teslimatları reddederek tekrar (replay) saldırısını engelleyin ve olay kimliğini idempotency anahtarı olarak kullanarak mükerrer işlemeyi önleyin.
- Güvenilir teslimat: Webhook teslimatı 'en az bir kez' ilkesiyle, üstel geri çekilmeli (exponential backoff) otomatik yeniden denemelerle çalışır; hızlı yanıt verip (200) işlemeyi arka planda yapın.
- Hız limitleri: HTTP 429 alındığında Retry-After başlığına uyun ve dağıtık (jitter) gecikmeyle yeniden deneyin; yüksek frekanslı ihtiyaçları webhook'a taşıyın.
- Toplu veri ve zaman dilimi: Geçmiş veriler için imleç (cursor) tabanlı sayfalama veya toplu dışa aktarma uç noktasını kullanın; tüm zaman damgaları UTC (ISO 8601) ve açık ayrıntı düzeyiyle gelir, böylece her mağazanın yerel günü ve yaz saati doğru ele alınır.
- Kimlik ve anahtar rotasyonu: API anahtarları, kesintisiz değişim için örtüşen (çift anahtar) rotasyonu ve TLS 1.3'ü destekler; canlı akışları bozmadan kimlik bilgilerini yenilersiniz.