Kupon Kodları

Kupon kodu doğrulama, misafirlere önceden üretilmiş kodlar aracılığıyla internet erişimi sağlar. Otel resepsiyonları, konferanslar ve kafeler gibi ön yüz personeliyle birebir temas gerektiren ortamlarda yaygın olarak kullanılır. Telefon numarası veya e-posta adresi gerekmez.

Kupon Türleri

Tür	Açıklama	Örnek Kullanım
Tek kullanımlık	Bir kez doğrulandıktan sonra geçersiz olur	Konferans katılımcı paketi
Çok kullanımlık	max_uses sınırına kadar farklı cihazlar tarafından kullanılabilir	Aile odası kodu
Süreli	expires_at tarihinden sonra geçersiz olur	Hafta sonu paketi

Türler birleştirilebilir: örneğin "5 kullanımlık, 3 gün geçerli" bir kupon oluşturulabilir.

Kupon Oluşturma

Konsol Arayüzü

Kuponlar → Yeni Kupon Oluştur ekranından:

• Kod uzunluğu ve formatı (alfanümerik, sayısal)
• Adet (toplu üretim)
• Maksimum kullanım sayısı
• Geçerlilik süresi
• Bant genişliği profili
• Günlük kota (MB)

Toplu İçe Aktarma (CSV)

Dışarıda üretilmiş kodları CSV formatında yükleyebilirsiniz:

code,max_uses,expires_at,bandwidth_profile,notes
HOTEL2026,10,2026-12-31,standard,Misafir odası 101
CONF-ABCD,1,2026-06-15,conference,Stant B12
VIP-SUITE,50,,premium,Süit misafirleri

expires_at boş bırakılırsa kuponun süresi dolmaz.

POS Entegrasyonu

Otel POS sistemleri veya kasa yazılımları, AnchorSpot REST API'si aracılığıyla programatik kupon oluşturabilir:

curl -X POST https://<console-host>/api/v1/vouchers \
  -H "Authorization: Bearer <api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "count":             1,
    "max_uses":          1,
    "expires_at":        "2026-06-09T12:00:00Z",
    "bandwidth_profile": "standard",
    "daily_quota_mb":    2048,
    "notes":             "Oda 214 - Koç Ailesi"
  }'

Yanıt:

{
  "vouchers": [
    { "id": "vch_9a3f", "code": "K7MP-X2QR", "status": "created" }
  ]
}

API Doğrulama Akışı

Captive portal, misafirin girdiği kodu aşağıdaki endpoint ile doğrular:

curl -X POST https://<portal-host>/api/v1/hotspot-portal/voucher/verify \
  -H "Content-Type: application/json" \
  -d '{
    "code": "K7MP-X2QR",
    "mac":  "aa:bb:cc:dd:ee:ff",
    "ip":   "192.168.10.45"
  }'

Başarılı yanıt:

{
  "status":       "authorized",
  "session_id":   "sess_3b8d21",
  "expires_at":   "2026-06-09T12:00:00Z",
  "uses_left":    null,
  "redirect_url": "https://..."
}

Hata durumları:

{ "error": "voucher_not_found" }
{ "error": "voucher_expired",   "expired_at": "2026-06-08T00:00:00Z" }
{ "error": "voucher_exhausted", "max_uses": 1, "current_uses": 1 }

Yarış Koşulu Güvenliği

Aynı kupon kodunun eş zamanlı iki cihaz tarafından kullanılması durumunda sayma işlemi atomik olarak gerçekleşir. PostgreSQL düzeyinde FOR UPDATE kilidi kullanılır; bu sayede max_uses sınırı kesinlikle aşılamaz.

:::info Teknik Detay Kupon tablosunda (tenant_id, code) ikilisi üzerinde UNIQUE kısıtlaması bulunur. Kod üretimi sırasında çakışma ihtimaline karşı yeniden deneme mekanizması devreye girer. use_count artışı UPDATE ... WHERE use_count < max_uses RETURNING * ile atomik olarak yapılır. :::

Kupon Yaşam Döngüsü

created → activated → used → expired

Durum	Açıklama
created	Oluşturuldu, henüz kullanılmadı
activated	En az bir kez kullanıldı, sınıra ulaşılmadı
used	max_uses sınırına ulaşıldı (tek kullanımlık için created → used direkt)
expired	Geçerlilik tarihi geçti

Bant Genişliği ve Kota Profilleri

Her kupona bir bant genişliği profili atanabilir:

Profil	İndirme	Yükleme	Günlük Kota
basic	2 Mbps	1 Mbps	500 MB
standard	10 Mbps	5 Mbps	2 GB
premium	50 Mbps	20 Mbps	Sınırsız
conference	5 Mbps	2 Mbps	1 GB

Profiller konsol'dan özelleştirilebilir (Ayarlar → Bant Genişliği Profilleri).

PDF Yazdırma ve QR Kod

Üretilen kuponlar PDF olarak indirilebilir. Her kupon için:

• İnsan tarafından okunabilir metin (büyük puntolu kod)
• QR kodu (portal URL + kod parametresi gömülü)
• Marka logosu ve özel mesaj (isteğe bağlı)

Kuponlar → [Seçili Kuponlar] → PDF İndir seçeneğiyle toplu indirme yapılır. Resepsiyon yazıcısından doğrudan basılabilir.

:::tip Otel Kullanımı Kupon kağıdı, check-in zarfına konulabilir veya oda anahtarıyla birlikte verilebilir. QR kodu sayesinde kod girişi olmadan telefonla tarama yeterlidir. :::

Kullanım Senaryoları

• Oteller — Her konuk için odaya özel kupon; checkout'ta otomatik süre sonu.
• Konferanslar — Katılımcı paketinde basılı kupon; SSID başına tek kullanımlık.
• Kafeler ve restoranlar — Yazar kasa entegrasyonuyla sipariş alındığında otomatik kupon üretimi.

Sorun Giderme

Kod Çalışmıyor

1. Kodun büyük/küçük harf duyarlılığını kontrol edin (varsayılan: büyük harf).
2. Kuponun expired veya used durumunda olmadığını Kuponlar ekranından doğrulayın.
3. SSID ile kupon profili eşleşiyor mu kontrol edin; bazı kuponlar belirli ağlarla kısıtlanmış olabilir.

CSV İçe Aktarma Hatası

CSV dosyasının UTF-8 kodlamasında kaydedildiğinden ve başlık satırının (code,max_uses,...) tam olarak eşleştiğinden emin olun. Hatalı satırlar içe aktarma raporunda belirtilir; geçerli satırlar yine de aktarılır.

:::warning Güvenlik Notu Kupon kodlarını herkese açık kanallarda (sosyal medya, e-posta listesi) paylaşmaktan kaçının. Ele geçirilen kodlar max_uses tükenene kadar kullanılabilir. :::