iGaming API Entegrasyonları

iGaming'de REST API, Webhook ve Olay İletimi

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.

Anlık istek yanıt kanalı ile ayrı asenkron olay bildirimleri akışına sahip API ağ geçidi
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.

KriterREST isteğiWebhook veya olay
Yönİstemci uç noktayı çağırırÜretici alıcıyı bilgilendirir
ZamanZaman aşımı öncesi yanıtOlay kaydedildikten sonra
AmaçOku veya işlem isteDurum değişikliğini bildir
OnaySözleşmedeki HTTP yanıtıTeslim alma yanıtı
HataTekrar çağır veya durum sorgulaYeniden ilet, kuyruğa al
TutarlılıkÇağrılan hizmetin sonucuAlı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.

  1. Komutu yetkilendirin ve ortak izleme kimliğini dış API çağrısından önce atayın.
  2. Yanıtı doğrulayın, oturum referansını saklayın, belirsiz zaman aşımını ayrı değerlendirin.
  3. İmzalı callback'i doğrulayın ve onay vermeden önce kalıcı idempotent kayıt oluşturun.
  4. Cüzdan durumunu bir kez işleyin, denetim ve analiz olaylarını güvenilir kayıttan üretin.
REST API isteği, kalıcı olay iletimi ve cüzdan, risk, denetim tüketicilerini ayıran üç panel
Aynı 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.

DurumGüvenli davranışSaklanacak kanıt
İlk geçerli bildirimDoğrula ve bir kez işleKaynak ve işlem ID'si
Aynı bildirim tekrarÖnceki sonucu döndürYanıt ve kayıtlı sonuç
Aynı ID, farklı tutarReddet ve araştırHer iki mesajın özeti
Sonucu belirsiz timeoutKayıtlı durumu sorgulaReferans ve işlem izi
İade veya geri almaAsıl kayıtla ilişkilendirAsı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]

  1. Kaynak sağlıyorsa nesne sürümü veya artan sıra numarası kullanın; geliş zamanından sıra uydurmayın.
  2. İzinli durum geçişlerini ve henüz gelmemiş öncül olayın nasıl bekleneceğini tanımlayın.
  3. Parasal kayıtları yetkili cüzdan defterinde tutun, ikincil ekranları ayrı güncelleyin.
  4. 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öntemiOperasyon kanıtı
Alıcı kısa süre kapalıGecikmeli tekrarDeneme ve son yanıt
Geçersiz mesajKarantina ve incelemeMesaj özeti ve neden
Tüketici sürümü hatalıDuraklat ve kayıttan tekrar işleSürüm ve kontrol noktası
Önceki olay eksikBeklet ve kaynak durumu sorNesne ve eksik ilişki
Defterler tutarsızDüzeltmeden önce araştırKaynak 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.

  1. Oyuncu, marka, pazar ve para birimi kapsamında izinli ve izinsiz çağrıları çalıştırın.
  2. Aynı callback'i yineleyin, tutarını değiştirin, sırasını bozun ve kayıt sonrası timeout oluşturun.
  3. Kuyruk birikimi, geçersiz imza, sağlayıcı kesintisi ve denetimli karantina tekrarını deneyin.
  4. 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]

Kaynaklar ve ek okumalar

Diyagram görüntüleyici