Platform entegrasyonu: Totem'in teknik gereksinimleri ve API akışı

Bu rehber, Totem platformuna entegrasyon sürecini teknik ekip bakış açısıyla ele alır. İçerik, totem casino giriş gibi operatör tarafı oturum yönetimi, API akışları, SDK gereksinimleri ve veri senkronizasyonu konularında pratik adımlar ve kontrol listeleri sunar. Aşağıdaki örnekler genel kabul görmüş endüstri uygulamalarına dayanmaktadır; canlı entegrasyon öncesi Totem'in resmi dokümantasyonunun doğrulanması tavsiye edilir.

Hangi sorunlara cevap verir?

  • Kimlik doğrulama ve oturum akışlarını nasıl kurmalısınız?
  • Gerçek zamanlı veri senkronizasyonu nasıl sağlanır?
  • SDK ve platform gereksinimleri nelerdir?
  • B2B entegrasyonunda adım adım test ve go-live süreci nasıl planlanır?

Genel mimari: bileşenler ve sorumluluklar

Tipik bir Totem entegrasyonu aşağıdaki bileşenlerden oluşur. Her bir bileşen için net sorumluluklar belirleyin:

  • Operator Client (Web / Mobile): Kullanıcı arayüzü, oturum başlatma, oyun başlatma istekleri.
  • Operator Backend: Kullanıcı profil yönetimi, cüzdan ara yüzü, oyun oturumlarına ilgili iş kuralları uygulayan sunucu tarafı.
  • Totem API: Kimlik doğrulama, oyuncu yönetimi, cüzdan işlemleri, oyun başlatma ve event'ler için arayüz.
  • Game Providers / Aggregator: Oyun akışı ve oyun kaynakları; Totem aracılığıyla çağrılabilir.
  • Veri Mağazası ve Raporlama: İşlem geçmişi, raporlar ve denetim günlükleri için saklama.

Kimlik doğrulama ve yetkilendirme (önerilen uygulamalar)

Entegrasyonun güvenilirliği için kimlik doğrulama ve yetkilendirme kritik önemdedir. Aşağıdaki yaklaşımlar yaygın ve uygulanması pratiktir:

  • API anahtarları + HMAC: Sunucu tarafı çağrılar için sabit API anahtarı ve isteklere HMAC imza ekleme.
  • OAuth 2.0 (client_credentials): Kısa ömürlü erişim tokenleri ile token yenileme mekanizması; erişim kapsamlarının (scopes) tanımlanması.
  • JWT: Taşınan yükte izin bilgileri taşınacaksa imzalı JWT kullanımı.

Uygulama notu: Sandbox ortamında token yenileme ve iptal akışlarını mutlaka test edin.

Tipik API akışları (adım adım)

Aşağıda entegrasyonda sık kullanılan temel akışların açıklaması ve örnek adımlar yer alır. Verilen endpoint isimleri örnektir; gerçek isimler Totem dokümanında farklı olabilir.

1) Yetkilendirme

  1. Operator backend, Totem OAuth token endpointine client_credentials ile istek atar.
  2. Totem erişim tokeni döner (kısa ömürlü).
  3. Backend, sonraki API çağrılarında Authorization: Bearer <token> kullanır.

2) Oyuncu kaydı / eşleştirme

  1. Operator, yeni bir oyuncu yaratırken Totem'e oyuncu bilgilerini gönderir: dış sistem kimliği, ülke, para birimi gibi temel alanlar.
  2. Totem oyuncu ID'si döner ve operator tarafında bu ID ile eşleme yapılır.

3) Cüzdan işlemleri

Cüzdan işlemleri (bakiye sorgulama, rezervasyon, onay/iptal) gerçek zamanlı ve idempotent olmalıdır:

  • /wallets/balance — bakiye sorgulama
  • /wallets/transactions — işlem başlatma (idempotency-key başlığı önerilir)
  • /wallets/transactions/{id}/commit veya /rollback — işlem sonucu

4) Oyun başlatma

  1. Operator, oyun başlatma isteğini Totem'e gönderir (oyun ID, oyuncu ID, parametreler).
  2. Totem veya aggregator, oyun oturumuna yönlendiren bir URL veya token döner.
  3. Client bu URL/token ile oyunu başlatır; oyun içi event'ler webhooks üzerinden bildirilebilir.

Veri senkronizasyonu: gerçek zamanlı vs toplu

Veri tutarlılığı için iki ana yaklaşım vardır:

  • Gerçek zamanlı (webhooks): Totem tarafından tetiklenen olaylar (ör. işlem tamamlandı, oyun sonucu) HTTP callback ile operatore iletilir. Webhook'lar idempotent işlenmeli ve doğrulama yapılmalıdır.
  • Toplu API/raporlar: Günlük veya saatlik toplu raporlar ile reconcile. Büyük hacimli veriler için tercih edilir.

Tavsiye: Kritik finansal işlemler için her iki yöntemin kombinasyonu (webhook + günlük raporlama) kullanılarak çakışmalar minimize edilir.

SDK gereksinimleri ve beklentiler

Totem ile entegrasyon için sağlanacak veya kullanılacak SDK'larda aşağıdaki gereksinimler işlevsellik ve güvenlik açısından fayda sağlar:

  • Platform desteği: Web (JavaScript), iOS (Swift), Android (Kotlin) için ayrı SDK paketleri veya REST/JSON tabanlı HTTP istemci kütüphaneleri.
  • Oturum yönetimi: token yenileme, otomatik re-authorization, güvenli token saklama yöntemleri.
  • Hata ve retry mekanizmaları: otomatik yeniden deneme politikaları, exponential backoff seçenekleri.
  • İzleme entegrasyonu: tek hata formatı, telemetry event'leri, request/response logging (kişisel verileri maskeleyerek).
  • Kriptografi: TLS 1.2+ zorunlu, istek imzalama için HMAC desteği.

B2B entegrasyon örneği: adım adım

  1. hesap oluşturma ve erişim: Totem sandbox hesabı açın, API anahtarları ve test client bilgilerini edinin.
  2. Sandbox doğrulaması: test oyuncuları yaratın, token yenileme ve iptal senaryolarını çalıştırın.
  3. Alan eşleme: operatör veritabanındaki oyuncu ID alanlarını Totem oyuncu ID ile eşleyin.
  4. Cüzdan işlemlerini test etme: rezervasyon, onay ve iptal akışlarını test edin; idempotency-key davranışını doğrulayın.
  5. Event işleme: webhook'ları kurun, imza doğrulama ve replay guard mekanizmalarını test edin.
  6. Performans testi: eşzamanlı istek yükü altında hata oranlarını ve gecikmeleri ölçün.
  7. Go-live checklist: canary dağıtım, izleme dashboard'ları ve otomatik alarmlar hazır olmalı.

Veri eşleme örnek tablosu

Operator Alanı Totem Örneği Açıklama
user_id playerId Dış sistem oyuncu kimliği ile Totem oyuncu ID eşlemesi
currency currency ISO 4217 formatında para birimi
balance wallet.balance Gerçek zamanlı bakiye sorgusu için kullanılacak alan
transaction_id transactionRef İşlemlerin idempotent işlenmesi için ortak anahtar

Hata yönetimi, rate limiting ve izleme

  • HTTP durum kodlarını anlamlı şekilde kullanın: 4xx istemci hataları, 5xx sunucu hataları.
  • Rate limit uygulanıyorsa Retry-After başlığına göre exponential backoff uygulayın.
  • Idempotency anahtarları ile aynı işlemin tekrar işlenmesinden doğabilecek tutarsızlıkları önleyin.
  • Loglama: işlem kimlikleri ve zaman damgalarını saklayın; hassas verileri maskeleyin.

Güvenlik ve uyum önerileri

Güvenlik tasarımı, hem teknik hem de operasyonel kontroller içermelidir:

  • Tüm trafik TLS 1.2 veya daha yükseği üzerinden gitmeli.
  • Webhook doğrulaması için imza doğrulama ve nonce/replay kontrolü uygulayın.
  • Erişim yetkilerini en az ayrıcalık ilkesiyle sınırlandırın; audit loglar oluşturun.
  • IP allowlist (gerekliyse) ve rate limiting uygulamalarını konfigüre edin.
  • Yasal ve uyum gereksinimlerini kontrol edin; yaş doğrulama, kimlik doğrulama ve ülke/tabanlı kısıtlamaları entegrasyon sırasında göz önünde bulundurun.

Test ve kademeli geçiş (go-live) adımları

  • Sandbox üzerinde tam fonksiyonel E2E testlerini tamamlayın.
  • Canary release ile küçük bir kullanıcı kümesinde canlı testi başlatın.
  • Metrikleri (hata oranı, gecikme, başarısız istekler) yakından izleyin; eşiklerin üzerinde artış varsa geri alım (rollback) planı hazır olsun.

Entegrasyon kontrol listesi (kısa)

  • Sandbox erişimi ve API anahtarları alındı mı?
  • Token yenileme senaryoları test edildi mi?
  • Webhook imza doğrulaması uygulandı mı?
  • İdempotent işlem mekanizması kuruldu mu?
  • Performans testi ve canary planı hazır mı?

Sınırlamalar ve son not

Bu dokümanda verilen endpoint isimleri ve örnek akışlar varsayımsal olup, Totem'in resmi API dokümantasyonundaki karşılıkları farklı adlandırmalar içerebilir. Canlı entegrasyon öncesi resmi teknik dokümanı inceleyin ve test ortamında tüm kritik senaryoları doğrulayın.

Sıkça sorulan sorular

Soru: Totem entegrasyonunda hangi kimlik doğrulama yöntemi tercih edilmelidir?

Cevap: Genellikle OAuth 2.0 client_credentials kısa ömürlü token ve HMAC imza kombinasyonu güvenli bulunur. Ancak hangi yöntemin kullanılacağı Totem ile imzalanan entegrasyon sözleşmesine ve operatörün altyapı tercihlerine bağlıdır.

Soru: Webhook'lar güvenli şekilde nasıl doğrulanmalı?

Cevap: Webhook mesajları, paylaşılan gizli anahtar ile HMAC-SHA256 gibi bir algoritma kullanılarak imzalanmalı; operatör tarafı bu imzayı doğrulamalı ve replay saldırılarını önlemek için nonce veya zaman damgası kontrolü yapmalıdır.

Soru: Veri senkronizasyonu için gerçek zamanlı mı yoksa toplu rapor mu tercih edilmeli?

Cevap: Kritik finansal olaylar için gerçek zamanlı webhook akışı, günlük reconcile için toplu raporlama kombinasyonu en sağlıklısıdır. Bu ikili yaklaşım tutarsızlıkları azaltır ve operasyonel doğrulama sağlar.

Soru: Go-live sırasında hangi metrikler kritik izlenmelidir?

Cevap: Hata oranı, ortalama gecikme (latency), başarısız isteklerin oranı, webhook teslim oranı ve işlem tutarsızlık sayıları öncelikli metriklerdir.