API anahtarının bağlı olduğu site bütün sunucu isteklerinin kapsamını belirler. Bu rehber güncel entegrasyon akışını açıklar; alanların ayrıntılı şeması uç nokta referansında ve `/sdk/openapi.json` dosyasındadır.

## Adresler ve ortam
- Sunucu API kökü: `PROVIDER_ORIGIN`/provider/v1.
- Oyuncu istemcisi ve `apiBase`: `PROVIDER_ORIGIN`/play/`SITE_SLUG`/.
- Sağlayıcı paneli: `ADMIN_ORIGIN`/admin/.
- Site paneli: `OPERATOR_ORIGIN`/operator/.
- API anahtarını panel domainine göndermeyin; panel oturumları sunucu API anahtarından ayrıdır.

Mevcut oyun adapter’ları public demo oturumları kullanır. Cüzdan bağlantısı site ayarına göre seamless veya transfer modunda çalışır. Public demo sonucunun finansal yetki sınırı RESULT-AUTHORITY.txt içinde açıklanır.

## Kimlik doğrulama ve kapsamlar
Sunucudan sunucuya çağrılar Authorization: Bearer başlığı kullanır. JSON gövdeli istekler Content-Type: application/json gönderir. Anahtar yalnız backend ortamında saklanır; tarayıcı Origin başlığı taşıyan sunucu API isteği kabul edilmez.

- launch: `/player`, `/launch` ve oyuncu oturumlarını kapatma.
- read: `/catalog`, `/rooms`, `/results`, `/stats`, bakiye ve `/events`.
- wallet: yalnız transfer cüzdanında kredi/borç ve transfer makbuzu.
- webhooks: `/webhooks/events` akışını okuma; `/events` için read gerekir.

Kaynak IP, anahtar süresi ve hem anahtarın hem sitenin izin listeleri uygulanır. Varsayılan kaynak socket adresidir; açıkça güvenilen proxy için `X-Real-IP` doğrulanır. Kurulum ayrıntısı ACCESS-SECURITY.txt içindedir. Yetki kapsamları OAuth scope değil, bu API anahtarının izinleridir.

## Oyuncu kimliği
`POST /player`, launch kapsamıyla hesabı eşler. Aynı tenant + `externalId`, aynı kalıcı oyuncuyu döndürür; tekrar çağrı yeni bakiye veya ad oluşturmaz. `externalId` 1–128 karakterdir ve doğrulanmış site üye anahtarından alınır. Harf, rakam ve - _ . : @ desteklenir.

```json Oyuncu eşleme gövdesi
{
  "externalId": "member-42",
  "name": "Atlas",
  "siteUsername": "atlas.site"
}
```

name, yeni hesapta site öneki yoksa gerekir; mevcut hesapta veya alias etkinse isteğe bağlıdır. `siteUsername` kaynak site bilgisidir, `publicId`’yi değiştirmez. `playerAliasPrefix`=cio yeni üyeye cio1001 gibi kalıcı ad verir. Eski adlar korunur. Bu alanların hiçbiri serbest tarayıcı girdisinden hesap seçmek için kullanılmaz.

`GET /player/{encodedExternalId}/balance`, read kapsamıyla player ve `walletMode` döndürür. `availableBalance` kullanılabilir, `lockedBalance` odada ayrılmış kuruş tutarıdır. SDK: `client.player()`, `client.balance(externalId)`. Aynı site bakiyesini kullanmak için SEAMLESS-WALLET.txt rehberini izleyin.

## Oyun oturumu
`POST /launch`, launch kapsamıyla HTTP 201 ve `launchTicket`, url, `apiBase`, `expiresAt`, `parentOrigin` alanlarını döndürür. Bilet 90 saniye geçerli ve tek kullanımlıdır. Her yeni açılışta yeni bilet alın; aynı üyelik korunur. İkinci açılış önceki oyuncu oturumunu geçersizleştirir.

```json Iframe oturumu gövdesi
{
  "externalId": "member-42",
  "name": "Atlas",
  "siteUsername": "atlas.site",
  "origin": "https://site.example",
  "route": "lobby",
  "mode": "iframe"
}
```

mode: iframe veya module. origin izin listesinde bulunan kesin protokol + host + port değeridir; path, query, wildcard veya kullanıcı bilgisi içermez. HTTPS gerekir; yerel loopback geliştirme için HTTP kullanılabilir.

route: lobby, catalog, providers, history, rankings, competitions, room/ID, watch/ID, replay/ID veya join/KOD. Oda ID’si 10 küçük hex karakter; davet kodu 8 büyük A–Z / 2–9 karakteridir. Paylaşım linki kendi site sayfanıza gider ve her ziyaretçi kendi oturumu için yeni launch alır. Linke token veya API anahtarı koymayın.

`POST /player/{externalId}/sessions/revoke`, launch kapsamı ve boş JSON gövdesiyle oyuncunun oyun/read oturumlarını ve kullanılmamış biletlerini kapatır. SDK: `client.revokeSessions(externalId)`.

## Katalog, odalar ve raporlar
- `GET /catalog` → games, currency=TRY, environment=sandbox. SDK: `client.catalog()`.
- `GET /rooms?status=all` → rooms. status: all, waiting, running, completed, cancelled. SDK: `client.rooms()`; filtre için `client.request('/rooms?status=waiting')`.
- `GET /results` → tamamlanan rooms. SDK: `client.results()`.
- `GET /stats?range=all` → statistics. range: all, today, week, month. Today İstanbul gün sınırı, week son 7 gün, month son 30 gündür. SDK: `client.statistics({range:'month'})`.

Katalog yalnız platformda ve sitede açık oyun/türleri döndürür. `buyAmounts` tam sayı kuruş teklifleridir; `bonusChoices` ilgili standart/süper bonus metadata’sını taşır. Ante/booster bir bonus-buy türü değildir. Çoklu seçimde tutar, seçilen bütün oyun ve bonus seçeneklerinin desteklediği ortak tutardan gelmelidir. Değişen fiyat/izin, eski seçimi sessizce başka bir türle değiştirmez.

Rapor alanları arasında `entryVolume`, refunds, `totalWinnings`, `paidPrizes`, `pendingPrizes`, commission, `providerRevenue`, `operatorShare`, `transferCredits`, `transferDebits`, income, expenses ve `netProfit` bulunur. Katılım hacmi veya cüzdana transfer kâr değildir. Oda listesi sınırlı geçmiş görünümüdür; mali mutabakat için cursor akışı ve raporlar birlikte kullanılır.

## Transfer cüzdanı — ayrı mod
Yeni entegrasyonda siteyle aynı harcanabilir bakiye için seamless kullanın. Aşağıdaki `/wallet/transfer` yalnız transfer modu içindir; seamless sitede kabul edilmez. Tüm tutarlar tam sayı kuruştur: 20000 = 200,00 TL. `amountMinor` 1–1.000.000.000 aralığındadır.

```json Transfer gövdesi
{
  "externalId": "member-42",
  "direction": "credit",
  "amountMinor": 20000,
  "reference": "credit-order-00042"
}
```

`POST /wallet/transfer`, wallet kapsamını ister. direction credit veya debit olur. reference 8–100 karakter; harf/rakam ve - _ . : kullanılır. Idempotency-Key başlığı verilirse reference ile birebir aynı olmalıdır. Aynı referans ve aynı içerik eski makbuzu döndürür; ikinci para hareketi oluşturmaz. Farklı içerikle aynı referans HTTP 409’dur.

Zaman aşımında yeni reference üretmeyin. `GET /wallet/transfers/{reference}` ile makbuzu okuyun veya aynı isteği aynı kimlikle sürdürün. Debit odada kilitli tutarı harcayamaz. SDK: `client.credit()`, `client.debit()`, `client.transferReceipt(reference)`. Kalıcı transfer örneği IDENTITY-WALLET.txt içindedir; seamless reserve/refund/settle işlemleri SEAMLESS-WALLET.txt içinde ayrı tanımlanır.

## Olay akışı ve tekrarlar
`GET /events?cursor=0&limit=100`, read kapsamını ister. `GET /webhooks/events` aynı defter akışını webhooks kapsamıyla verir. İkisi de pull API’dir; ödeme callback’i değildir. Seamless cüzdanın imzalı callback protokolü ayrıdır.

cursor negatif olmayan tamsayı, limit 1–200’dür. Yanıt events ve `nextCursor` içerir. Her event.id/cursor kaydını tekilleştirin; olaylar ve yeni cursor aynı veritabanı işleminde kaydedilmelidir. Boş yanıtta cursor değişmez. Hata durumunda aynı cursor’dan devam edin. SDK: `client.events(cursor)`, `client.webhookEvents(cursor)`.

## Ortak odalar ve kesinleşme
Yeni odalar ortak havuzda açılır; oyuncunun site kimliği ve kaynak cüzdanı değişmez. Her istemci kendi `/play/SITE_SLUG/` `apiBase` adresini ve kendi launch/read oturumunu kullanır. Başka siteye ait `externalId`, bakiye, makbuz veya token oyuncularla paylaşılmaz. Özel odanın davet şartı ortak havuzda da geçerlidir.

Oyun havuzu sınırı `capabilities.maxGamePool` üzerinden okunur; varsayılan 20’dir. Seçilen bonus türü ve fiyat bir kez dondurulur, bütün koltuklarda aynı uygulanır. Site/oyun/bonus/tutar politikaları katılım ve başlangıçta doğrulanır. Rastgele seçim, sayfa yenilenince tekrarlanmaz.

Oda oluşturulurken `feeBps`, katılımda koltukların `providerShareBps` değerleri kaydedilir. 500 bps = %5. Doğrulanmış toplam kazançtan `floor(totalWinnings × feeBps / 10000)` kesilir; en yüksek skor net havuzu alır. Eşitlikte bölünür, artan kuruşlar koltuk sırasına göre dağıtılır. Komisyon kaynak sitelere oyuncularının brüt kazancı oranında ayrılır; site payı kendi dondurulmuş sağlayıcı/operatör oranıyla bölünür. Toplam ödül + komisyon = brüt kazanç korunur.

completed savaşın bittiğini gösterir. Ödül ancak `settlementStatus`=complete ise hesaba aktarılmış gösterilir; pending kaynak cüzdan mutabakatının sürdüğünü belirtir. Belirsiz turda yeni satın alma veya tahmini sonuç üretilmez. Oda kontrol talebi ve yetkili inceleme akışı ROOM-REVIEWS.txt içindedir.

## Hatalar ve işletim
Hatalar JSON error ve code alanlarıyla gelir. SDK hata nesnesinde status/code bulunur; ağ zaman aşımı kesin işlem reddi değildir.

- 400: alan, değer veya referans biçimi geçersiz.
- 401: kimlik doğrulama geçersiz veya süresi dolmuş.
- 403: kapsam, kaynak IP veya origin izin vermiyor.
- 404: kaynak ya da makbuz bulunamadı.
- 409: çakışma, yetersiz bakiye veya geçersiz durum.
- 415: JSON gövdesi gerekli.
- 429: hız sınırı; aynı işlem kimliğini koruyarak kontrollü bekleyin.
- 503: bakım veya yeni katılımlar duraklatılmış.

API anahtarı, imza sırrı ve launch/player/read token’larını loglardan çıkarın. HTTPS/WSS, kesin origin listesi, uygun CSP ve güvenilir proxy yapılandırması gerekir. Cüzdan outbox/makbuzlarını kalıcı tutun; yedekten dönüşte operatör defteriyle mutabakat yapın. Yerel tarayıcı testleri fiziksel mobil, dış ağ veya yüksek oda kapasitesi kabulü değildir.

## İlgili rehberler
README.txt kurulum örneklerini; WALLET-CONFIG.txt callback ayarlarını; ACCESS-SECURITY.txt anahtar/IP/2FA sınırlarını; OPERATOR-API.txt site personeli ve destek akışını; CHAT-MODERATION.txt sohbet yetkilerini açıklar. Panel API’leri operatör sunucu anahtarı değil, kendi panel cookie/CSRF oturumlarını kullanır.

## Dönem savaşları — site raporu

Günlük, haftalık ve aylık katılımları Operatör / Dönem savaşları sayfasından izle. Yalnız kendi sitenin katılımcıları, özel üye kimlikleri, tutarları ve ödülleri görünür; genel sıra tüm sitelerden hesaplanır. Personel izinleri: `rooms.read`, `players.read`, `finance.read`. Sunucudan `GET /provider/v1/competitions?kind=daily&limit=50&offset=0` (`read` kapsamı) veya `client.competitions({kind: 'daily'})` kullan. Para birimi TRY, tutarlar kuruştur. Ödenen ve bekleyen ödül ayrıdır. Dönem rehberindeki sayfalama, olay bağlamı ve paket güncelleme adımlarını uygula: [PERIOD-WARS.txt](PERIOD-WARS.txt). Iframe bağlantısı korunur; modül için güncel istemci ZIP'i gerekir.
