> ## Documentation Index
> Fetch the complete documentation index at: https://developer.leaderos.net/llms.txt
> Use this file to discover all available pages before exploring further.

# API Temelleri

> Kimlik doğrulama, yanıt biçimi, hata kodları, çeviri, para birimi, captcha ve ödeme akışı.

Base URL: `https://siteniz.com/headless/v1`

## Kimlik doğrulama

İki katman vardır:

> [tab] Public key
>
> Her istekte zorunludur (tarayıcıdan açılan yönlendirme rotaları hariç):
>
> ```http theme={null}
> X-LeaderOS-Key: pk_live_XXXXXXXX
> ```
>
> Alternatif olarak `?key=pk_live_...` sorgu parametresi de kabul edilir.

> [tab] Bearer token
>
> Giriş gerektiren endpoint'ler için oyuncunun token'ı:
>
> ```http theme={null}
> Authorization: Bearer <token>
> ```
>
> Token, `POST /auth/login` veya `POST /auth/register` yanıtında gelir. `POST /auth/logout` ile iptal edilir.

> [!WARNING]
>
> 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](https://developer.leaderos.net/headless/tr/sdk-and-react.md)).

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

```json theme={null}
{
  "success": true,
  "data": { },
  "message": "Çevrilmiş mesaj (varsa)",
  "meta": {
    "pagination": { "page": 1, "perPage": 10, "total": 42, "lastPage": 5 },
    "seo": { "page": "blog", "title": "…", "description": "…", "image": "…" }
  }
}
```

Hata:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "…",
    "fields": { "email": { "required": "E-posta gerekli" } }
  }
}
```

**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:

| Kod | Anlam | Ön yüzde yapılacak |
| - | - | - |
| `EMAIL_REQUIRED` | Hesapta e-posta yok | E-posta isteyin → `POST /auth/email` |
| `TFA_REQUIRED` | 2FA doğrulanmadı | Kodu isteyin → `POST /tfa/verify` |
| `EMAIL_NOT_VERIFIED` | E-posta doğrulanmamış | Doğrulama ekranını gösterin |
| `UNAUTHENTICATED` (401) | Token gerekli | Giriş sayfasına yönlendirin |
| `INVALID_TOKEN` (401) | Token süresi dolmuş / çıkış yapılmış | Token'ı silin, giriş gösterin |
| `ACCOUNT_BANNED` | Hesap yasaklı | Bilgi ekranı |
| `MAINTENANCE` (503) | Bakım modu | Bakım ekranı |

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

| Başlık | Etki |
| - | - |
| `X-Locale: tr` | Mesajlar ve içerik dili. Alternatif: `?lang=tr`, `Accept-Language` |
| `X-Currency: TRY` | Fiyatların gösterileceği 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:

| `next` | Yapılacak |
| - | - |
| `redirect` | `api.payments.start(intent)` ile tarayıcıyı yönlendirin |
| `manual` | `/payment/pay/manual/{orderId}` sayfasını gösterin |
| `success` | Kredi ile ödendi, başarı sayfasına gidin |
| `external` | `paymentUrl` adresini açın ve `notice` metnini gösterin |

Ö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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.