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

# Kullanım Örnekleri

> Plugin API'yi kendi eklentinizden, botunuzdan veya arka ucunuzdan çağırmak için örnekler.

Aşağıdaki örneklerde `https://siteniz.com` yerine kendi sitenizi, `API_ANAHTARINIZ` yerine **Ayarlar → API** sayfasındaki anahtarı kullanın.

> [!WARNING]
>
> Bu örnekler **sunucu tarafında** çalışmalıdır (oyun sunucusu, bot sunucusu, kendi backend'iniz). API anahtarını asla tarayıcıya veya oyunculara ulaşan bir yere koymayın.

## İstemci kurulumu

```js Node.js theme={null}
const BASE = 'https://siteniz.com/api';
const KEY = process.env.LEADEROS_API_KEY;

async function leaderos(method, path, body) {
  const res = await fetch(BASE + path, {
    method,
    headers: { 'X-Api-Key': KEY },
    // Form gövdesi: JSON değil!
    body: body ? new URLSearchParams(body) : undefined,
  });
  const json = await res.json().catch(() => null);
  if (json && json.status === false) throw Object.assign(new Error(json.error), { code: json.error, json });
  return json;
}
```

```php PHP theme={null}
<?php
function leaderos(string $method, string $path, array $body = []) {
    $ch = curl_init('https://siteniz.com/api' . $path);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_HTTPHEADER     => ['X-Api-Key: ' . getenv('LEADEROS_API_KEY')],
        CURLOPT_RETURNTRANSFER => true,
    ]);
    if ($body) curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($body));
    $json = json_decode(curl_exec($ch), true);
    curl_close($ch);
    return $json;
}
```

```python Python theme={null}
import os, requests

BASE = "https://siteniz.com/api"
HEADERS = {"X-Api-Key": os.environ["LEADEROS_API_KEY"]}

def leaderos(method, path, data=None):
    r = requests.request(method, BASE + path, headers=HEADERS, data=data)  # data= form gönderir
    return r.json()
```

```java Java theme={null}
HttpClient client = HttpClient.newHttpClient();
String form = "target_username=" + URLEncoder.encode("Steve", UTF_8) + "&amount=25";
HttpRequest req = HttpRequest.newBuilder(URI.create("https://siteniz.com/api/credits/add"))
    .header("X-Api-Key", apiKey)
    .header("Content-Type", "application/x-www-form-urlencoded")
    .POST(HttpRequest.BodyPublishers.ofString(form))
    .build();
String body = client.send(req, HttpResponse.BodyHandlers.ofString()).body();
```

## Kullanıcı ve bakiye

```bash theme={null}
# Kullanıcı adı veya ID ile
curl -H "X-Api-Key: API_ANAHTARINIZ" "https://siteniz.com/api/users?username=Steve"
curl -H "X-Api-Key: API_ANAHTARINIZ" "https://siteniz.com/api/credits?userID=42"
```

`GET /users` yanıtı şifre hariç hesap bilgilerini ve `linkedAccounts` nesnesini (ör. `{ "discord": "1234…" }`) içerir.

## Kredi işlemleri

```js theme={null}
await leaderos('POST', '/credits/add',    { target_username: 'Steve', amount: 50 });
await leaderos('POST', '/credits/remove', { target_username: 'Steve', amount: 10 });
await leaderos('POST', '/credits/set',    { target_username: 'Steve', amount: 100 });

// Oyuncudan oyuncuya (kredi modülünde "kredi gönderme" açık olmalı)
await leaderos('POST', '/credits/send', {
  sender_username: 'Steve',
  target_username: 'Alex',
  amount: 5,
});
```

> [!TIP]
>
> Örneğin bir oy verme ödülü, etkinlik ödülü veya Discord seviye sistemi için `/credits/add` kullanabilirsiniz. Ekleme ve çıkarma işlemleri oyuncunun kredi geçmişine yazılır; `/credits/set` yazılmaz.

## Kredi ile ürün satın alma

Ürünler form dizisi olarak gönderilir:

```bash theme={null}
curl -X POST https://siteniz.com/api/store/buy \
  -H "X-Api-Key: API_ANAHTARINIZ" \
  -d "userID=42" \
  -d "products[0][id]=12" \
  -d "products[0][quantity]=1" \
  -d "products[1][id]=7" \
  -d "products[1][variables][3]=kirmizi"
```

```js theme={null}
await leaderos('POST', '/store/buy', {
  userID: 42,
  'products[0][id]': 12,
  'products[0][quantity]': 1,
});
```

Satın alma sitedeki kurallarla aynı çalışır: indirimler, abonelik yükseltme, zorunlu ürünler, zorunlu bağlı hesaplar, vergi, stok ve cashback uygulanır; komutlar ve roller teslim edilir. Olası hatalar: `INSUFFICIENT_BALANCE`, `OUT_OF_STOCK`, `REQUIRED_PRODUCT`, `REQUIRED_LINKED_ACCOUNT`, `DOWNGRADE_NOT_ALLOWED`, `INVALID_VARIABLE`.

Oyun içi mağaza menüsü için `GET /store/listing?username=Steve` oyuncuya özel kategori ağacını, nihai fiyatları ve yükseltme bilgisini verir.

## Roller

```bash theme={null}
# Rol ver (expiryDate boş = süresiz)
curl -X POST https://siteniz.com/api/users/42/roles \
  -H "X-Api-Key: API_ANAHTARINIZ" \
  -d "roleID=3" -d "expiryDate=2026-12-31 23:59:59"

# Rolü değiştir (URL'deki 3 = mevcut rol)
curl -X PATCH https://siteniz.com/api/users/42/roles/3 \
  -H "X-Api-Key: API_ANAHTARINIZ" \
  -d "roleID=5"

# Rolü kaldır
curl -X DELETE https://siteniz.com/api/users/42/roles/5 -H "X-Api-Key: API_ANAHTARINIZ"
```

## Destek talepleri

```js theme={null}
const { data } = await leaderos('POST', '/support/tickets', {
  userID: 42,
  categoryID: 1,
  title: 'Ödeme sorunu',
  message: 'Kredim yüklenmedi.',
});

await leaderos('POST', `/support/tickets/${data.id}/close`);
```

Talep açıldığında Discord webhook bildirimi (ayarlıysa) gönderilir.

## Discord botu

```bash theme={null}
curl -H "X-Api-Key: API_ANAHTARINIZ" https://siteniz.com/api/integrations/discord/users/123456789012345678
curl -H "X-Api-Key: API_ANAHTARINIZ" https://siteniz.com/api/integrations/discord/roles
curl -H "X-Api-Key: API_ANAHTARINIZ" https://siteniz.com/api/integrations/discord/settings
```

Discord ID ile kullanıcıyı ve rollerini alıp, `discordRoleID` eşlemesiyle sunucunuzdaki rolleri eşitleyebilirsiniz.

## Bağışçı tablosu (scoreboard, hologram)

```bash theme={null}
curl -H "X-Api-Key: API_ANAHTARINIZ" "https://siteniz.com/api/store/donations?type=top-monthly&limit=5"
```

`type`: `top-alltime`, `top-annual`, `top-monthly`, `top-daily`, `latest`. `limit`: 1–10.

## Hata yönetimi

```js theme={null}
try {
  await leaderos('POST', '/store/buy', { userID: 42, 'products[0][id]': 12 });
} catch (e) {
  switch (e.code) {
    case 'INSUFFICIENT_BALANCE': /* "Yeterli krediniz yok" */ break;
    case 'OUT_OF_STOCK':         /* "Stokta yok" */ break;
    case 'VALIDATION':           console.log(e.json.message); break;
    default:                     console.error(e.code);
  }
}
```

> [!NOTE]
>
> Hata mesajları İngilizcedir ve değişebilir. Oyunculara göstereceğiniz metni **`error` koduna göre** kendi dilinizde üretin.

## İpuçları

* **Önbellek:** `/store/listing`, `/store/products`, `/vote-links` gibi sık değişmeyen verileri eklentinizde birkaç dakika önbelleğe alın.
* **Asenkron çağrı:** Oyun sunucularında API çağrılarını ana iş parçacığında (main thread) yapmayın; sunucu donabilir.
* **Kullanıcı adı:** Minecraft sitelerinde `username` parametreleri oyuncunun gerçek adıyla (`realname`) eşleştirilir; diğer oyunlarda hesap kullanıcı adıyla.
* **Saat dilimi:** Tarihler sitenin saat dilimindedir (Discord kullanıcı ucundaki rol bitiş tarihleri hariç; onlar UTC).


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