# ARENA BATTLE — OPERATÖR FATURALAMA

## 1. Kapsam ve hesaplama
Hizmet faturaları, oyuncu cüzdanından ve sağlayıcının operatöre ödeyeceği komisyonlardan ayrıdır. Fatura yayımlamak veya ödendi işaretlemek oyuncu bakiyesini değiştirmez. Ortak oyun havuzundaki zarar, kazanan oyuncunun sitesine otomatik borç yazılmaz.

İlk kurulumda otomasyon ve e-posta kapalıdır. Tutar modeli belirlenene kadar `manual` kullanılır: yönetici taslağa hizmet kalemlerini girer, sonra yayımlar. `fixed` modeli sözleşmede kararlaştırılmış sabit aylık bedeli kullanır. `provider_share_v1` yalnız kapanmış ayın kesinleşmiş oda sonuçlarından hesaplanan sağlayıcı komisyon payını taslağa alır; manuel inceleme gerekir. Dönem savaşları, oyun zararları ve oyuncu bakiyeleri bu hesaplamaya dahil değildir.

Model ve sürümü, şirket bilgileri, vergi oranı, dönem özeti ve kalemler faturada saklanır. Yeni ayarlar geçmiş faturaları değiştirmez. PDF ticari hizmet dökümüdür; vergi idaresine bağlı resmi e-fatura entegrasyonu içermez. Şirket, vergi ve banka bilgileri işletmenin doğrulanmış bilgileriyle doldurulmalıdır.

## 2. Aylık akış ve panel
Ana admin > Faturalar > Faturalama ayarları bölümünde düzenleyen şirketi ve ödeme talimatını gir. Site filtresinden operatörü seçip Site ayarları üzerinden alıcı, e-posta, dil, bedel, vergi, fatura günü ve vadeyi belirle.

Fatura günü 1–28, vade 1–90 gündür. Dönemler İstanbul saatine göre takvim aylarıdır; otomasyon seçilen gün geldiğinde bir önceki kapanmış ayı işler. Aynı site ve ay için tek kayıt oluşturulur. Otomasyon tarafından oluşturulan, değişmemiş ve onaylı sabit bedelli taslaklar otomatik yayımlanabilir; manuel veya komisyon modeli taslakları otomatik yayımlanmaz.

Taslak > ödeme bekliyor > ödendi akışı kullanılır. Kısmi tahsilat desteklenir. Yayımlanan kalemler değiştirilemez. Hiç ödeme almamış fatura gerekçeyle iptal edilebilir. İptal kaydı korunur; aynı ay için ikinci fatura oluşturulmaz. Ödemeli belgeyi düzeltmek için muhasebe incelemesi gerekir; sistem banka hesabından tahsilat veya otomatik iade yapmaz.

Operatör > Faturalar kendi sitesinin belgelerini, kalemlerini, dönem özetini, kalan borcunu, ödeme geçmişini ve PDF dosyasını gösterir. Diğer sitelerin faturaları görünmez. Ana admin ödeme kaydedince operatörün durumu bir sonraki yenilemede güncellenir.

Panel dili admin ve operatörde personel hesabına ayrı kaydedilir; farklı cihaz dahil sonraki girişlerde geri yüklenir ve her zaman değiştirilebilir. Oturum gerektiren `GET /control/api/preferences` ve `GET /operator-api/preferences` mevcut hesabın tercihini döndürür. Aynı adrese `PATCH` yalnız `{"locale":"tr"}` veya `{"locale":"en"}` alır; Origin ve CSRF doğrulaması gerekir. Başka hesap ID’si kabul edilmez. Null dil, henüz hesap tercihi kaydedilmediği anlamına gelir.

## 3. Panel API uçları
Bu uçlar panel oturum çerezi kullanır. Operatör entegrasyon API anahtarı kullanılmaz. Değişikliklerde ilgili panel Origin ve `X-CSRF-Token` gerekir. Admin okuma `finance.read`, yazma `finance.manage`; operatör okuma `finance.read` ister.

```http Yönetici
GET /control/api/billing?tenant=all
PATCH /control/api/billing/settings
PATCH /control/api/billing/sites/:tenantId
POST /control/api/billing/invoices
GET /control/api/billing/invoices/:invoiceId
PATCH /control/api/billing/invoices/:invoiceId
GET /control/api/billing/invoices/:invoiceId/pdf
POST /control/api/billing/invoices/:invoiceId/issue
POST /control/api/billing/invoices/:invoiceId/payments
POST /control/api/billing/invoices/:invoiceId/void
POST /control/api/billing/invoices/:invoiceId/email
```

```http Operatör — yalnız kendi sitesi
GET /operator-api/billing
GET /operator-api/billing/invoices/:invoiceId
GET /operator-api/billing/invoices/:invoiceId/pdf
```

```json Taslak oluşturma gövdesi
{"tenantId":"SITE_ID","period":"2026-09","reference":"monthly:2026-09"}
```

```json Kısmi ödeme kaydı — banka referansı tekil olmalı
{"amountMinor":250000,"reference":"bank-receipt-20261015-001","note":"Banka ekstresiyle doğrulandı"}
```

Tutarlar TRY kuruş olarak tam sayıdır. Aynı ödeme referansı ve aynı içerikle tekrar istek ikinci ödeme yazmaz. Aynı referans farklı içerikle reddedilir. Açık tutarı aşan ödeme reddedilir. `issue` boş JSON gövdesi alır. `void` için en az 5 karakter `reason` gerekir. PDF indirirken oturum gerekir; belge herkese açık bağlantıyla sunulmaz.

## 4. E-posta ve PDF
Posta bilgileri yalnız sunucunun korumalı ortamında tutulur. İstemci paketine, operatör API anahtarına veya tarayıcıya eklenmez.

```text Sunucu ortam değişkenleri
BILLING_SMTP_HOST=smtp.example.com
BILLING_SMTP_PORT=587
BILLING_SMTP_USER=YOUR_SMTP_USER
BILLING_SMTP_PASSWORD=YOUR_SMTP_PASSWORD
BILLING_MAIL_FROM=Arena Battle <billing@example.com>
```

587 STARTTLS veya 465 TLS kullanılır; sertifika doğrulaması ve TLS 1.2 alt sınırı zorunludur. Global e-posta anahtarı ve site e-posta anahtarı birlikte açık olmalıdır. PDF ekli fatura, ödeme bildirimi ve isteğe bağlı vade hatırlatması gönderilir. PDF indirme dili admin/operatör panelinde seçili dildir (`?lang=tr` veya `?lang=en`). Parametre yoksa faturada kayıtlı dil kullanılır. Desteklenmeyen veya tekrarlanan dil parametresi reddedilir. Yalnız sunum değişir; fatura tutarları ve asıl kayıtlar değişmez. E-posta ve ekindeki PDF, faturadaki alıcı diliyle gönderilir. Özel açıklamalar ve ödeme talimatları yazıldığı gibi korunur. Maildeki panel bağlantısı oturum açmayı gerektirir.

Kuyruk veritabanında kalıcıdır. Vade hatırlatmaları en fazla üç haftalık aralık için oluşturulur. SMTP kabulü alıcı gelen kutusuna teslim garantisi değildir. Gönderimin sonucu belirsizse otomatik yeniden gönderilmez; personel posta kutusu ve SMTP kayıtlarını kontrol ettikten sonra tekrar gönderir. SMTP tanımlı değilse panel bunu açıkça gösterir, gerçek gönderim yapılmaz.

## 5. Site risk varsayılanları
Operatör > Risk ve uyarılar ekranında varsayılan kurallar hazır gelir. Site yalnız kendi eşiklerini düzenler veya platform varsayılanlarına döner. Kurallar ve API ayrıntıları için Risk ve bildirimler rehberine bak.

Aynı IP veya cihaz, tekrarlı rakip, yüksek kazanç, sıra dışı kazanma oranı ve hızlı katılım inceleme sinyalidir; tek başına hile kanıtı değildir. Bu sinyaller otomatik para kesmez, kazancı iptal etmez veya oyuncuyu engellemez. Başlamış oyunlar risk kuralıyla iptal edilmez.

## 6. Kurumsal başvuru personeli
Kurumsal sağlayıcı sitesindeki başvurular ana adminin İş ortaklığı talepleri bölümüne gelir. Ayrı panel gerekmez. Ekip ve roller bölümünde yalnız `inquiries.read` ve gerekiyorsa `inquiries.manage` yetkili özel rol oluştur; personel hesabına bu rolü ata. Bu hesap finansı, oyuncuları veya site API anahtarlarını göremez.

## 7. Kurulum ve doğrulama
Fatura listeleri `page` parametresiyle 50 kayıtlık sayfalara ayrılır. `summary` tutarları yalnız açık sayfayı değil, seçilen sitenin tüm fatura geçmişini kapsar.

Önce şirket ve banka bilgilerini, alıcı adresini, sözleşme bedelini ve vergi oranını doğrula. Ayrı test verisiyle taslak, PDF, yayımlama, kısmi/tam ödeme ve site sınırlarını kontrol et. Gerçek e-posta gönderimini yalnız doğrulanmış test alıcısıyla sınadıktan sonra otomasyonu aç. Veritabanını ve mevcut şifreleme anahtarlarını birlikte yedekle.

Iframe ve oyuncu modülünün cüzdan/API sözleşmesi değişmez; oyuncu dosyalarını yalnız faturalama için yeniden dağıtmak gerekmez. Güncel toplu entegrasyon paketi bu rehberin iki dilini içerir. Ticari model değişirse yeni model sürümü ve yeni dönem taslakları kullanılır; yayımlanmış belgeler geriye dönük yeniden hesaplanmaz.
