# Kimlik doğrulama ve genel kurallar

## Bot token'ı

Botun her istekte token'ını şu başlıkla gönderir:

```
Authorization: Bot <token>
```

Token'ı [geliştirici portalında](https://noluyo.net/gelistirici/uygulamalar) uygulamanı oluştururken veya token'ı yenilerken alırsın. `Bot` sözcüğü ve ardından gelen tek boşluk tam bu şekilde yazılmalıdır.

Token, bota açık rotalarda geçerlidir; bu rotaların tamamı [REST referansında](https://noluyo.net/gelistirici/api.md) listelenir. Bota açık olmayan bir rota `403 bot_forbidden` döner. Botun olayları dinlemek için bağlandığı [gateway](https://noluyo.net/gelistirici/gateway.md) aynı token'ı kullanır ama başlıkta değil, identify çerçevesinde ve `Bot ` öneki olmadan. Adresini [`GET /gateway/bot`](https://noluyo.net/gelistirici/api-gateway.md#getGatewayBot) söyler; kişilerin kullandığı `/gateway` adresi bot token'ını `4004` ile reddeder.

## Token'ını koru

Token botun kendisidir: onu ele geçiren, botunun adına mesaj atabilir ve botun izinlerini kullanabilir.

- Token'ı koda yazma, depoya gönderme, ortam değişkeninde veya bir sır yöneticisinde tut.
- Token yalnızca oluşturulduğunda ve yenilendiğinde gösterilir. Daha sonra görüntülenemez.
- Sızdığından şüpheleniyorsan hemen portaldan **Token'ı yenile** ile yenile. Eski token o anda çalışmaz olur, açık gateway bağlantıları da `4004` ile kapanır.

Token belirli bir biçim taşımaz; ayrıştırmaya çalışma, olduğu gibi saklayıp gönder.

Şu durumlarda geçerli görünen bir token da `401 unauthorized` alır: uygulama silinmişse, token yenilenmişse, bot hesabı ya da uygulama sahibinin hesabı kapatılmış veya silinmişse.

## İstek kuralları

**Adres.** Tüm rotalar `https://noluyo.net/api/v1` altındadır.

**Gövde.** JSON gövdeli isteklerde tek bir JSON nesnesi gönder. En fazla 1 MiB olabilir; aşarsa `413 body_too_large` döner. Bozuk JSON `400 invalid_body` verir. Gövde isteyen bir rotaya boş gövde göndermek de `invalid_body` verir; hiçbir alanı değiştirmeyeceksen bile `{}` gönder.

**Bilinmeyen alanlar.** Bot isteklerinde tanınmayan alanlar yok sayılır, hata vermez.

**ID'ler metindir.** Tüm ID'ler 64 bitlik sayılardır ve yanıtta da istekte de metin olarak yazılır: `"111600000000000000"`. Gövdede ID'yi sayı olarak gönderirsen `invalid_body` alırsın. ID'ler oluşturulma zamanına göre sıralanır.

**İzinler metindir.** İzin değerleri ondalık metindir: `"68672"`. Bkz. [İzinler](https://noluyo.net/gelistirici/izinler.md).

**Zamanlar.** Yanıtlardaki zamanlar RFC 3339 biçimindedir. İstekte de aynı biçimi kullan: `"2026-11-05T12:00:00Z"`.

**`@me`.** `/users/@me` botun kendisidir. Üye rotalarının çoğunda `user_id` yerine `@me` yazabilirsin; ban rotaları gerçek bir kullanıcı ID'si ister.

**Kısmi güncelleme.** `PATCH` isteklerinde yalnızca gönderdiğin alanlar değişir. Boş bırakılabilen alanlarda `null` değeri temizler.

**Yanıt kodları.** Başarılı bir yanıt `200`, `201` veya gövdesiz `204` olabilir. Beklediğin kodu her rotanın referansında bulursun. Mesaj göndermek `201` değil, `200` döner.

## Mesajlarda biçim

- Kullanıcı etiketi: `<@kullanici_id>`
- Rol etiketi: `<@&rol_id>`. Rolün etiketlenebilir olması veya botun `MentionEveryone` iznine sahip olması gerekir.
- Herkesi etiketleme: `@everyone`, `@here`, `@herkes`, `@burada`. `MentionEveryone` izni olmadan metin olarak kalır, kimseye bildirim gitmez.
- Sunucu emojisi: `<:ad:id>`, hareketliyse `<a:ad:id>`. Botun kullanamadığı emoji `:ad:` metnine dönüşür.

Bir mesajda en çok 50 kullanıcı ve 50 rol etiketlenir; fazlası sayılmaz. Mesaj metni en çok 2000 karakterdir.

## Dosya göndermek

Dosyalar `multipart/form-data` ile gönderilir. JSON, `payload_json` adlı parçaya; dosyalar `files[0]`, `files[1]` gibi adlandırılmış parçalara konur. Bir mesajda en çok 10 dosya olur ve bunun için `AttachFiles` izni gerekir.

```bash
curl -X POST "https://noluyo.net/api/v1/channels/$CHANNEL_ID/messages" \
  -H "Authorization: Bot $BOT_TOKEN" \
  -F 'payload_json={"content":"Rapor ekte"}' \
  -F 'files[0]=@rapor.txt'
```

Başka adla bir parça `invalid_body` verir. Bir dosya yükleme sınırını aşarsa `413 file_too_large` döner. Yanıttaki dosya adresi siteye göreli, imzalı bir bağlantıdır ve en az 24 saat geçerlidir. Süresi dolunca mesajı yeniden okuyarak yenisini al.

---

Yalnızca portalın yaptıklarını otomatikleştirmek istersen bir başka kimlik daha vardır: kişi oturumu. Bot kurmak için gerekmez; bkz. [API ile yönetmek](https://noluyo.net/gelistirici/bot-uygulamalari.md).

## Bu sayfayı yapay zekaya verirsen

> **İpucu:** Yapay zekaya doğrudan HTTP isteği yazdırırken şunları ekle:
>
> - Bot isteklerinde `Authorization: Bot <token>` başlığı kullanılır (`Bearer` yalnızca OAuth2 kullanıcı token'ları içindir).
> - Sunucu belgelenmemiş JSON alanlarını sessizce yok saymaz; `invalid_body` ile reddeder, bu yüzden yalnızca şemadaki alanlar gönderilir.

## Sırada ne var

- [Hız sınırları](https://noluyo.net/gelistirici/rate-limit.md): `X-RateLimit-*` başlıkları ve `429` bekleme kuralları
- [Güvenlik](https://noluyo.net/gelistirici/guvenlik.md): token saklama ve sızıntı durumunda yenileme
- [Hatalar](https://noluyo.net/gelistirici/hatalar.md): kimlik ve doğrulama hata kodları