Bir casino platformu REST API ile oyun oturumu başlatabilir; ancak bahis sonucu, geri ödeme veya ödeme onayı daha sonra gelebilir. Bu değişiklikler çoğu zaman ilk HTTP yanıtının içinde değil, webhook ya da mesaj kuyruğunda iletilir. Her iki yolu birlikte tasarlamak gerekir: istek başarılı olduğu halde zaman aşımına uğrayabilir, aynı bildirim tekrar gönderilebilir, ayrı hizmetler olayları farklı sırayla görebilir. Bu rehber komutlarla gerçekleşmiş olayları ayırır; finansal işlemler için gerekli doğrulama, izlenebilirlik ve hata kurtarma tasarımını operatör açısından açıklar.
Yayın tarihi
Anlık API yanıtı ile sonradan gelen olay, güvenilir bir entegrasyonun farklı yükümlülükleridir.
İçindekiler
REST API, webhook ve olaylar ne işe yarar?
HTTP tabanlı REST API, oyun listesini almak, oyuncuyu doğrulamak, oturum açmak veya tanımlı bir işlemi istemek gibi anlık iletişim için kullanılır. Webhook, başka bir sistemin gerçekleşen olayı bildirmek amacıyla gönderdiği HTTP çağrısıdır. Dahili bir mesaj aracısı benzer olayları herkese açık webhook uç noktası olmadan dağıtabilir. Hangi yöntemin neyi garanti ettiği her sağlayıcının sözleşmesine bağlıdır.
HTTP 200, yalnızca ilgili uç noktanın tanımladığı sonucu ifade eder; diğer hizmetlerin güncellendiğini kanıtlamaz. Webhook, ilk bağlantı kapandıktan sonra ulaşabilir. OpenAPI HTTP arayüzlerini, AsyncAPI olay tabanlı arayüzleri tanımlamaya yarar; bu belgeler çalışır durumda güvenilir teslimatı kendiliğinden sağlamaz. [1] [2]
İstek-yanıt ile olay teslimatı nasıl karşılaştırılır?
İstek-yanıt iletişiminde çağrıyı yapan taraf belirlenen süre içinde sonuç bekler. Olay iletiminde durum değişikliği daha sonra bir veya birden çok alıcıya bildirilir. Güvenilirlik yalnızca yönteme dayanmaz; dayanıklı depolama, yeniden deneme sözleşmesi ve alıcı tarafın doğru işlemesi gerekir.
Kriter
REST isteği
Webhook veya olay
Yön
İstemci uç noktayı çağırır
Üretici alıcıyı bilgilendirir
Zaman
Zaman aşımı öncesi yanıt
Olay kaydedildikten sonra
Amaç
Oku veya işlem iste
Durum değişikliğini bildir
Onay
Sözleşmedeki HTTP yanıtı
Teslim alma yanıtı
Hata
Tekrar çağır veya durum sorgula
Yeniden ilet, kuyruğa al
Tutarlılık
Çağrılan hizmetin sonucu
Alıcılar geç güncellenebilir
Örneğin oyun başlatma API'si oturum belirtecini hemen verirken cüzdan ve raporlama servisleri tur olaylarını sonradan işler. Webhook alıcısı uzun görevleri kuyruğa ayırmadan önce en azından gerekli kalıcı alındı kaydını oluşturmalıdır. [3]
Sürümlü olay sözleşmesinde hangi alanlar olmalı?
Olay zarfı, mesaj kimliğini tanımladığı ticari işlemin kimliğinden ayırmalıdır. Olay ID'si, tür, şema sürümü, oluşma zamanı, üretici, ilişkilendirme ID'si ve operatör kapsamını belirleyen alanlar gereklidir. Parasal işlemlerde tutar, para birimi ve durumun anlamı kesin tanımlanmalıdır.
Olay ID'sini işlem ID'sinden ayırın; tek işlemin farklı aşamalarında birden fazla olay çıkabilir.
Zaman damgasının anlamını, para birimini, isteğe bağlı alanları ve sürüm geçişini belgeleyin.
Kimlikler küresel olarak eşsiz değilse operatör, marka, sağlayıcı ve hesap bağlamını taşıyın.
İletim girişimi ve imza gibi üst verileri, gerçek bahis veya ödeme sonuçlarından ayırın.
OpenAPI ve AsyncAPI makinece okunabilen sözleşmeler sunar. Bunun yanında iade, geri alma ve itirazlı tur örnekleri de gerekir. Uyumsuz olay değişikliklerini sessiz alan yeniden adlandırmaları olarak değil planlı geçişler olarak yönetin. [1] [2]
Casino API komutundan olay akışına hangi adımlar var?
Oyuncu oturum açtığında arka uç kimlik, marka, izinli oyun ve sunucu kimlik bilgilerini denetler. Harici servis oturumu açar veya zaman aşımı nedeniyle sonucu belirsiz bırakabilir. Sonraki bahis, kazanç ve iptal mesajları oyuncu, oturum, tur ve kaynak sağlayıcıyla eşleştirilebilmelidir. Tarayıcıdaki oyun adresi tek başına yeterli kimlik değildir.
Komutu yetkilendirin ve ortak izleme kimliğini dış API çağrısından önce atayın.
Yanıtı doğrulayın, oturum referansını saklayın, belirsiz zaman aşımını ayrı değerlendirin.
İmzalı callback'i doğrulayın ve onay vermeden önce kalıcı idempotent kayıt oluşturun.
Cüzdan durumunu bir kez işleyin, denetim ve analiz olaylarını güvenilir kayıttan üretin.
⊕Diyagramı büyütAynı bildirimin tekrar gelmesi tek oyun turunu birden fazla finansal işleme dönüştürmemelidir.
The Aggregator'ın herkese açık cüzdan callback rehberi sağlayıcıya göre tanımlanan işlem kimliğini ve tekrar gönderim davranışını örnekler. Bu süre ve kurallar bütün iGaming API'leri için geçerli sayılmamalıdır. [7]
Tekrar deneme ve idempotent kayıt nasıl tasarlanır?
Ağ kesintisi nedeniyle gönderen taraf onayı görmeyebilir; alıcı ise işlemi önceden kaydetmiş olabilir. Yeniden gönderilen olay doğru bir kurtarma davranışıdır ancak ikinci para hareketi yaratmamalıdır. Kaynağın ve iş operasyonunun kapsamını içeren benzersiz anahtar, kalıcı veritabanı kısıtıyla korunmalıdır. Geçici bellek önbelleği tek işlem garantisi vermez.
Durum
Güvenli davranış
Saklanacak kanıt
İlk geçerli bildirim
Doğrula ve bir kez işle
Kaynak ve işlem ID'si
Aynı bildirim tekrar
Önceki sonucu döndür
Yanıt ve kayıtlı sonuç
Aynı ID, farklı tutar
Reddet ve araştır
Her iki mesajın özeti
Sonucu belirsiz timeout
Kayıtlı durumu sorgula
Referans ve işlem izi
İade veya geri alma
Asıl kayıtla ilişkilendir
Asıl ve iade ID'leri
Stripe desteklenen API çağrılarında idempotency key kullanımını, webhook teslimatında ise farklı korumaları belgeler. Dışarı gönderilen istek anahtarı gelen casino callback'lerini otomatik olarak tekilleştirmez. [3] [4]
Sıralama ve gecikmeli tutarlılık neden önemli?
Mesajın alınma sırası gerçek işlem sırasını yansıtmayabilir. Bonus olayı hesap güncellemesinden, geri alma ise ilk bahis kaydından önce ulaşabilir. Amazon SQS standart kuyrukları için en az bir kez teslimat ve bazı durumlarda sıra değişikliği açıkça belgelenmiştir. Bu, küresel sıralama varsayımının neden riskli olduğuna dair bir örnektir. [5]
Kaynak sağlıyorsa nesne sürümü veya artan sıra numarası kullanın; geliş zamanından sıra uydurmayın.
İzinli durum geçişlerini ve henüz gelmemiş öncül olayın nasıl bekleneceğini tanımlayın.
Parasal kayıtları yetkili cüzdan defterinde tutun, ikincil ekranları ayrı güncelleyin.
Bekleyen olayları, işlem gecikmesini ve eksik referansları görünür hale getirin.
Sıralama garantileri sistemin tamamı için değil nesne ya da bölüm bazında belirtilmelidir. Kaynak sıra bilgisi sunmuyorsa olayları saatine göre dizmek yerine yetkili işlem kaydıyla mutabakat yapmak gerekir.
Webhook imzası ve API yetkisi nasıl kontrol edilir?
Herkese açık webhook uç noktası bir güven sınırıdır. Alıcı, sözleşmede tanımlanan yöntemle göndericiyi doğrulamalı, destekleniyorsa ham istek üzerinden imzayı kontrol etmeli, tekrar oynatma zaman aralığını ve ilgili hesap/işlem yetkilerini denetlemelidir. HTTPS aktarımı korur; her JSON içeriğini güvenilir kılmaz.
İşlem yapmadan önce imza ve zamanı doğrulayın, anahtar değiştirme sürecini planlayın.
Sadece endpoint erişimini değil oyuncu, cüzdan ve işlem düzeyinde yetkiyi kontrol edin.
Yük boyutu, hız, işleme süresi ve tekrarları sınırlayın; kişisel verileri loglara dökmeyin.
Test ve canlı anahtarları ayırın, elle tekrar oynatmaları ve mutabakat erişimini kaydedin.
Stripe kendi webhook imza mekanizmasını açıklar; OWASP API risklerinde yetkilendirme, kimlik doğrulama ve kaynak tüketimi sorunlarını vurgular. Casino sağlayıcısına uygulanan algoritma yine onun gerçek sözleşmesine dayanmalıdır. [3] [6]
Kuyruk hataları ve kayıp olaylar nasıl kurtarılır?
Güvenilir alıcı, doğrulanmış mesajı onay vermeden önce kalıcı olarak saklar ve kontrollü bir işleyiciye aktarır. Geçici ve kalıcı hatalar ayrılmalı, sorunlu içerik karantinaya alınmalı ve denetlenen bir yeniden işleme prosedürü bulunmalıdır. Şema doğrulaması başarısız olan mesaj ağ hatasıymış gibi sonsuza kadar tekrar edilmemelidir.
Hata türü
Kurtarma yöntemi
Operasyon kanıtı
Alıcı kısa süre kapalı
Gecikmeli tekrar
Deneme ve son yanıt
Geçersiz mesaj
Karantina ve inceleme
Mesaj özeti ve neden
Tüketici sürümü hatalı
Duraklat ve kayıttan tekrar işle
Sürüm ve kontrol noktası
Önceki olay eksik
Beklet ve kaynak durumu sor
Nesne ve eksik ilişki
Defterler tutarsız
Düzeltmeden önce araştır
Kaynak ve defter kayıtları
Kuyruğun teslim alındı onayı finansal kaydın işlendiği anlamına gelmez. AWS'nin sıra ve karantina örnekleri yöntemleri açıklar; saklama ve yeniden oynatma sürelerini operatörün sözleşmesel yükümlülükleri belirlemelidir. [5]
Olay izlemede ve mutabakatta hangi veriler gerekli?
Tek bir iş operasyonu HTTP çağrısından olay üreticisine, her gönderim denemesine ve ilgili tüketicilere kadar izlenebilmelidir. En eski bekleyen olayın yaşı, son başarılı teslimat, yeniden deneme oranı, bastırılan tekrarlar, şema redleri ve açık finansal farklar takip edilmelidir. Yeşil sağlık kontrolü her mesajın tamamlandığına kanıt değildir.
İlişkilendirme ID'si ile istek, olay, oturum, oyun turu ve işlem ID'lerini ayrı saklayın.
Sağlayıcı kayıtlarını, cüzdan defterini ve raporları planlı aralıklarla karşılaştırın.
Hataların yanında beklenen olayların açıklanamayan sessizliğine de alarm kurun.
Olay müdahalesi, elle tekrar işleme ve oyuncu bilgilendirme sorumlularını belirleyin.
İtirazlı bir oyun turunda CRM için dönüştürülmüş olay yeterli değildir; kaynak işlem ID'leri korunmalıdır. Mutabakat farkı otomatik telafi ödemesi değil kontrollü inceleme başlatmalıdır.
Canlıya geçişten önce hangi senaryolar test edilmeli?
Kabul testi yalnızca başarılı oturum çağrısını değil gerçekçi arızalarda uçtan uca davranışı da göstermelidir. API sürümü, olay abonelikleri, idempotent kapsamı, iade kuralları, veri saklama ve destek kanalları yazılı olmalıdır. Bakiye, limit veya ihtilaf sonucunu etkileyen tüm hizmetler sınanmalıdır.
Oyuncu, marka, pazar ve para birimi kapsamında izinli ve izinsiz çağrıları çalıştırın.
Aynı callback'i yineleyin, tutarını değiştirin, sırasını bozun ve kayıt sonrası timeout oluşturun.
Her test işlemini sağlayıcı kaydı, cüzdan defteri, olay ve denetim izleriyle mutabık kılın.
REST API, webhook ve olay iletimi ayrı özellikler olarak değil tek bir denetlenebilir entegrasyon olarak ele alınmalıdır. Gerçek ölçüt, komutların, olayların ve parasal kayıtların hata altında tutarlı, izlenebilir ve kurtarılabilir olmasıdır. [1] [2] [7]