Ana içeriğe atla
Base URL: https://siteniz.com/headless/v1

Kimlik doğrulama

İki katman vardır:
Her istekte zorunludur (tarayıcıdan açılan yönlendirme rotaları hariç):
Alternatif olarak ?key=pk_live_... sorgu parametresi de kabul edilir.
Bearer token’ı asla localStorage’a veya istemci durumuna koymayın. Next.js şablonu token’ı httpOnly çerezde saklayan bir proxy rotası kullanır (bkz. SDK ve React).
OpenAPI’de her endpoint için hangi kimlik doğrulamasının gerektiği belirtilir: yalnızca key, key + Bearer (giriş zorunlu), key + isteğe bağlı Bearer veya hiçbiri (tarayıcı yönlendirmeleri).

Yanıt biçimi

Hata:
Her zaman error.code değerine göre dallanın, message’a göre değil. Mesajlar çevrilir ve değişebilir; kodlar sabittir.
  • Sayfalama: ?page=2; sonuç meta.pagination içindedir.
  • Görseller mutlak URL olarak döner.
  • Parasal tutarlar temel para biriminde sayıdır; ziyaretçinin para birimine çevrilmiş metin için *Formatted alanlarını kullanın.

Hesap korumaları (403)

Giriş yapmış ama bir adımı tamamlamamış hesaplar şu hataları alır. Ön yüzünüz bunları yakalayıp ilgili ekrana yönlendirmelidir: Tüm hata kodları ve anlamları OpenAPI’de her endpoint’in x-error-codes alanında, ayrıca MCP’deki list_error_codes aracında bulunur.

Dil ve para birimi

Çeviri dosyaları GET /i18n/{code} ile alınır. İngilizce metin anahtardır; SDK ve şablon bunu t('English text') ile kullanır.

Captcha (Cloudflare Turnstile)

GET /site/config yanıtındaki captcha alanı şunları içerir: enabled, provider, siteKey ve her sayfa için gerekli olup olmadığı (pages: login, register, forgot_password, open_ticket, post_thread…). İlgili sayfada gerekliyse formdan aldığınız Turnstile token’ını gövdede captchaToken olarak gönderin. Başarısızlıkta CAPTCHA_FAILED döner. React paketindeki <Turnstile page="login" onToken={...} /> bileşeni bunu sizin için yapar ve captcha gerekmiyorsa hiçbir şey çizmez.

Modül ve özellik kontrolü

Bir özelliği çizmeden önce config.modules[slug].active değerine bakın. Kapalı bir modülün endpoint’leri 404 döner. React’te useModule('forum'), sunucuda isModuleActive(config, 'forum') kullanılır.

Yönlendirmeli akışlar (handoff)

Ödeme sayfası veya Discord/harici sağlayıcı gibi tarayıcının başka bir siteye gitmesi gereken işlemlerde API bir tek kullanımlık URL (handoff) döner. SDK’da leaderos.payments.start(intent) tarayıcıyı bu adrese götürür. URL 60 saniye geçerlidir ve bir kez kullanılabilir. Ödeme isteği (PaymentIntent) şu next değerlerinden birini döndürür: Ödeme sonrası oyuncu, panelde tanımladığınız Ödeme başarılı / hatası sayfalarına döner. CONTACT_REQUIRED hatası ad/telefon bilgisi istendiği anlamına gelir.

Hız sınırı

Headless API’nin yerleşik bir hız sınırı yoktur (ana sitede de yoktur). Canlıda Cloudflare gibi bir servisle /headless/v1/auth/* ve /headless/v1/*/send gibi hassas uçlara hız sınırı kuralı eklemeniz önerilir.

Lisans ve marka

  • API, sitenizin lisansını sunucu tarafında doğrular (5 dakika önbellek).
  • config.branding.canRemove değeri false ise “Powered by LeaderOS” bağlantısı ön yüzünüzde görünür olmalıdır.