API ve kimlik bilgileri

Yetkileri ayrı tutun#

Sunucu lisansı sunucuyu doğrular. Panel işlemleri ayrıca uygun hesap yetkilerini gerektirir. Yükleme tokenları kanıt yükleme bağlamıyla sınırlıdır ve süreleri dolar; panel yönetimi için kullanılamaz.

Güvenilir entegrasyon kurun#

Kimlik doğrulama hataları, zaman aşımı ve hız sınırlarında sık tekrar döngülerinden kaçının. Sonucu belirsiz finansal yazmayı otomatik tekrar etmeyin. Yetkilendirme başlıklarını tarayıcı kodunda, URL’lerde veya loglarda göstermeyin.

Uç nokta, kimlik bilgisi ve yetkiyi eşleştirin#

Farklı entegrasyonların tek bir evrensel anahtarı yoktur. Kayıtlı sunucu lisansı SaaS veritabanı köprüsünü doğrular. Bileşen API token’ı uç noktaya özel kapsam isteyebilir. Personelin tarayıcı işlemi oturum açmış hesabın rol ve yetkisini, ilgili değişikliklerde CSRF korumasını gerektirir. Kanıt yükleme token’ı bağlam, sunucu ve isteğe bağlıdır; yönetici token’ı değildir.

Yerleşik köprü başlığının biçimi aşağıdadır. YOUR_SERVER_LICENSE yer tutucudur; çalışan kimlik bilgisi değildir. Protokol gövdesini resource kendisi gönderir. Rastgele JSON’a bu başlıkları eklemek geçerli iş oluşturmaz. Kimlik doğrulama başlığını sunucular arası trafikte tutun; tarayıcı koduna, URL parametresine, analitik kaydına veya paylaşılan hata çıktısına koymayın.

Authorization: Bearer YOUR_SERVER_LICENSE
Content-Type: application/json

• Sunucu lisansını saklama

Kuyruk sonucunu ve hatayı ayrı değerlendirin#

Köprü uç noktası POST JSON kabul eder; tarayıcının verdiği SQL metni veya tablo adı kabul etmez. Kuyruğa alınmış ya da teslim edilmiş iş hâlâ devam eder. Oyuncu okuması veya bakiye değişimi başarılı demeden tamamlanmış sonucu ve işlem durumunu inceleyin. HTTP yanıtı ile işin son sonucu farklı şeylerdir.

• 401 unauthorized: kimlik bilgisinin doğru sunucuya ait olduğunu ve yenilenmediğini doğrulayın.
• 403 bridge_disabled, subscription_inactive veya permission_denied: sunucunun Tosun Connect kartını (bridge_disabled, bağlantının orada kapatıldığını gösterir), ücretli durumu ve hesap yetkisini inceleyin; tekrar denemek erişim vermez.
• 405 / 415: HTTP yöntemi ve JSON Content-Type kontrol edilmeli. Bozuk JSON veya beklenmeyen alan düzeltilmeli, sürekli aynı istek gönderilmemeli.
• 429: varsa Retry-After süresine uyun ve aralığı artırın. Yerleşik köprü eşzamanlı işi sınırlar ve hatada gecikmeyi artırır.
• 503 veya timeout: anahtarsız saat, sunucu/istek referansı kaydedin; bağlantıyı ve hizmet durumunu araştırın.

• Köprü işlemleri ve hata açıklamaları

En küçük yararlı işlemle test edin#

Önce test sunucusu veya kontrollü karakter kullanın. Tek okuma yapın, dönen karakteri doğrulayın ve oyunla karşılaştırın. Köprü sabit işlemleri ve sayfalamayı destekler; sınırsız veritabanı dökümü değildir. İki ayrı okumayı aynı işlemin tekrarından ayırmak için istek referansını saklayın.

Yalnız durum, süre ve gizli olmayan referans kaydedin. Genel hata raporlarından token ve kişisel oyuncu bilgisini çıkarın. Kimlik bilgisi, yetki veya paket değiştiğinde bu testleri yineleyin.

Aynı yönetim token’ını bütün entegrasyonlara dağıtmayın. Bileşen kimlik bilgisi varsa yalnız gereken kapsamı kullanın ve kullanılmayan kimlik bilgilerini iptal edin. Uç nokta veya hesap yetkisi değiştiğinde yalnız başarılı yolu değil reddedilen yolu da yeniden test edin; aylar önceki başarılı isteği yeterli saymayın.

1. Doğru sunucuda başarıyı, yanlış veya iptal edilen kimlik bilgisiyle reddi doğrulayın.
2. Yetkisi olmayan personelin işlem yapamadığını kontrol edin; başka müşterinin sunucusunda denemeyin.
3. Entegrasyonunuzun pending, failed, expired ve done durumlarını nasıl gösterdiğini doğrulayın. Hepsini genel başarı mesajına çevirmeyin.
4. Para değişiminde unknown_outcome araştırılmalıdır. Yeni yazma düşünmeden canlı bakiye ve işlem kaydını okuyun.

• Performans ve sınırlı istekler
• Framework uyumluluğu

Tarayıcı isteği ile sunucu protokolünü ayırın#

/api/tenant_db_bridge.php personelin oturumuyla çalışan panel yoludur. POST, application/json, geçerli _csrf ve aynı tenant’a ait hesap gerekir; gövde sınırı 4096 bayttır. action alanı enqueue veya result olabilir. Sunucu lisansını buraya göndermek tarayıcı oturumu oluşturmaz. Hesabın okuma hakkı bulunması para yazma yetkisi olduğu anlamına gelmez; ilgili işlem yetkisi ayrıca denetlenir.

/api/server_db_bridge.php ise resource’un sunucudan gönderdiği sağlık, iş alma ve sonuç protokolüdür. POST JSON ve Bearer sunucu lisansı kullanır; gövde sınırı 65536 bayttır. Tarayıcı çerezini veya CSRF değerini bu protokolün yerine kullanmayın. Geliştirirken hangi yolu çağırdığınızı önce belirleyin; birinin kimlik bilgisini diğerinin isteğine eklemek erişim hatasını çözmez. Yerleşik resource’un protokolünü rastgele JSON ile taklit etmeyin.

İstek kabulünü tamamlanan sonuçtan ayırın#

ok=true, HTTP isteğinin kabul edildiğini gösterebilir; kuyruklu oyun işleminin tamamlandığını tek başına göstermez. request içindeki id, operation ve status alanlarını birlikte izleyin. pending bekleyen, claimed sunucunun aldığı iştir; done tamamlanmış sonucu, failed başarısızlığı ve expired süresi dolmuş işi ifade eder. Sonuç okumada aynı server_id ve request_id bağlamını koruyun.

Son durum ve error alanını kontrol etmeden kullanıcıya başarı yazmayın. Bekleyen aynı parametreli istek mevcut iş kaydına dönebilir; bu davranışı kalıcı ve sınırsız yeniden gönderim garantisi sanmayın. Özellikle para yazmasında unknown_outcome görülürse yeni yazmayı durdurun: zaman aşımı veya geçersiz sonuç, etkinin hiç oluşmadığını kanıtlamaz. Canlı bakiye, önceki hedef ve denetim kaydı üzerinden mevcut işlemi inceleyin; kayıt silerek tekrar denemeyin.

Geliştirici hata kaydını küçük ve temiz tutun#

405 için yöntemi, 415 için JSON Content-Type değerini, 400 için geçerli JSON ve izin verilen alanları kontrol edin. Tarayıcı yolunda 401 oturumu, 419 CSRF doğrulamasını araştırın; sayfayı normal gezinmeyle yeniden açın. 404 durumunda doğru sunucu ve istek bağlamını kontrol edin, başka müşterinin kaydını denemeyin. 429 sırasında sürmekte olan işleri bekleyin.

503 veya belirsiz ağ sonucunda hata zamanı, uç nokta, HTTP durumu, operation ve gizli olmayan istek referansını kaydedin. Aşağıdaki örnek yalnız destek notudur, gönderilecek API gövdesi değildir. Çerez, Authorization, _csrf, lisans ve oyuncu verilerini rapora koymayın. Yetki veya gövde hatasını hızlı yeniden denemelerle örtmek yerine sorumlu aşamayı düzeltin; doğrulama için önce tek kontrollü okuma kullanın.

Endpoint: /api/tenant_db_bridge.php
Method: POST
HTTP status: 419
Error: csrf_failed
Operation: players.list
Reference: YOUR_REQUEST_REFERENCE
Time: YOUR_ERROR_TIME

Bir oyuncu listesini iki doğrulanmış JSON gövdesiyle okuyun#

Aşağıdaki örnek, hesabınızın panelinde oturum açmış tarayıcıdan ilk oyuncu sayfasını okumayı anlatır. Sunucu 123 ve istek kimliği kurgu değerlerdir; kendi sunucunuzu ve enqueue yanıtındaki request.id değerini kullanın. CURRENT_PAGE_CSRF yerine mevcut sayfanın geçerli CSRF değerini koyun. Bu değer sunucu lisansı değildir ve destek notuna kopyalanmaz. Aynı kaynağa gönderilen POST, application/json ve tarayıcı oturumu gerekir. Okuma için servers.manage veya players.view yetkisi aranır; demo modunda enqueue reddedilir.

İlk gövdede yalnız boş cursor gönderilir; bu işlem en fazla 25 kayıtlık sayfa döndürebilir. limit, SQL, tablo adı, bağlantı dizesi veya para parametresi eklemeyin. İlk yanıt pending ise ikinci gövdeyle aynı işi sorgulayın; yeni enqueue göndererek ikinci iş açmayın. done sonucunda request.result.items listesini okuyun. request.result.has_more doğruysa sonraki bilinçli sayfa isteğinde request.result.next_cursor değerini kullanın; boş listeyi hatasız tamamlanmış sonuçtan ayrı yorumlamayın. Verilen JSON şablonları çalışır kimlik bilgisi içermez. Denemeyi kendi test sunucunuzda tek bir okuma ile sınırlayın; örneği herkese açık tarayıcı eklentisine yönetici erişimi dağıtmak için kullanmayın.

POST /api/tenant_db_bridge.php
Content-Type: application/json

Enqueue:
{
  "_csrf": "CURRENT_PAGE_CSRF",
  "server_id": 123,
  "action": "enqueue",
  "operation": "players.list",
  "params": {"cursor": ""}
}

Result (use request.id from the enqueue response):
{
  "_csrf": "CURRENT_PAGE_CSRF",
  "server_id": 123,
  "action": "result",
  "request_id": "00112233445566778899aabbccddeeff"
}

• MySQL köprüsü
• Panel ve hesap erişimi

Ağ zaman aşımını işin süresiyle karıştırmayın#

Örneğin enqueue saat 14:03:10’da kabul edildi ve request.id kaydedildi; sonraki result isteği bağlantı sorunu nedeniyle tamamlanmadı. Paneldeki tek HTTP isteği 12 saniyede durabilir, kuyruktaki işin süresi ise oluşturulmasından itibaren 120 saniyedir. Tarayıcının isteği bırakması sunucudaki işi iptal etmez. Bu nedenle “yanıt gelmedi” gözlemini expired veya failed sonucu gibi sunmayın. Bilinen iş kimliğini koruyun, ağ düzeldikten sonra aynı server_id ile result okuyun. Normal panel akışı bekleyen sonucu üç saniyelik aralıklarla izler; sık aralıkta sorgu döngüsü eklemeyin.

Örnekte salt okunur players.list işi sonunda expired ve request_expired dönerse hatayı kaydedip bağlantı koşullarını düzelttikten sonra yeni bir okuma başlatabilirsiniz. player.money.set işinde claimed sonrasında expired veya geçersiz sonuç unknown_outcome oluşturabilir: bu, bakiye değişmedi demek değildir. Yeni yazmayı durdurun, güncel bakiyeyi ve mevcut işlem kaydını araştırın. Sonuçlar sınırsız arşiv değildir; süresi dolmuş kayıtlar daha sonra sınırlı temizlikle kaldırılır. Kayıt artık bulunamıyorsa yeni para isteğiyle sonucu tahmin etmeyin. Destek için yalnız gizli olmayan referans, zaman, operation ve son bilinen durumu saklayın.

Illustrative observations; not an API request body:
14:03:10  enqueue accepted; save request.id
14:03:22  HTTP timeout; job outcome is not established
Later     result with the same server_id + request_id

Read:  expired + request_expired -> investigate before a new read
Write: expired + unknown_outcome -> stop writes and reconcile

• MySQL köprüsü
• Performans ve bekleme aralıkları