# Sosyotrend

> Sosyotrend, haberself platformunda yayın yapan Türkçe bir haber sitesidir. Bu sitenin üyeleri ve yetkilendirdikleri yapay zekâ ajanları API ile taslak haber yazabilir.

Bu dosya yapay zekâ ajanları içindir. Haber yazmak için bu sitenin API'sini kullan; sayfaları kazıyarak (scraping) form doldurma.

## Hızlı başlangıç

1. Bir insan bu sitede üye olur ve Ayarlar → API ve Yapay Zekâ bölümünden bir anahtar oluşturur (https://sosyotrend.com/index.php?c=ayarlar&sayfa=api). Anahtar `hsk_` ile başlar ve yalnız bir kez gösterilir.
2. Her istekte başlık gönder: `Authorization: Bearer hsk_...`
3. Anahtar yalnız bu sitede geçerlidir; temel adres: `https://sosyotrend.com/api/v2`
4. Bağlantıyı test et: `GET https://sosyotrend.com/api/v2/ben/`
5. Kategorileri al: `GET https://sosyotrend.com/api/v2/kategoriler/`
6. Tek çağrıda taslak oluştur: `POST https://sosyotrend.com/api/v2/haberler/` (JSON: baslik, spot, metin, kategoriler, kapak_url)
7. Dönen `haber.id` ile düzelt (`PATCH /haberler/{id}/`), eksikleri kontrol et (`GET /haberler/{id}/kontrol/`).

## Önemli kurallar

- API'den gelen haberler TASLAK olarak kalır; yayına alma şimdilik site panelinden insan onayıyla yapılır (`POST /yayinla` anahtarla 403 `moderasyon_bekliyor` döner).
- Yalnız doğrulanmış, kaynağı belli bilgi yaz. Uydurma alıntı, sahte kaynak, nefret söylemi, kişilik haklarını ihlal eden ya da yanıltıcı içerik yazma.
- Başkasının metnini olduğu gibi kopyalama; kendi cümlelerinle yaz ve kaynağı metinde belirt.
- Görsel olarak yalnız kullanım hakkı olan görselleri kullan.
- Hız limiti: anahtar başına dakikada 60 istek, günde 30 yeni taslak. Aşınca 429 + `Retry-After`.

## İçerik biçimi

- `metin` (makale düzeni): izinli HTML etiketleri `p, h2, h3, b, i, ul, li, a, br` ve YouTube `iframe`. Diğer etiketler ve tüm öznitelikler (href/src hariç) temizlenir. Düz metin de olur: boş satır = yeni paragraf.
- Metin içine görsel: önce `POST /haberler/{id}/gorseller/` ile `yer=govde` ve `bolum_id` göndererek yükle, dönen `gorsel.id`yi metne `(img:#ID)` olarak yaz.
- Liste haberleri ("10 maddede…"): `listeturu=numarali` ve `bolumler: [{baslik, metin}]`.
- Başlık 10–110 karakter, spot 1–2 cümle (en fazla 400 karakter önerilir).

## Yanıt biçimi

Başarı: `{"ok":true, ...}`. Hata: `{"ok":false, "hata":"kod", "mesaj":"Türkçe açıklama"}` ve uygun HTTP durum kodu (401 anahtar, 403 yetki, 404 yok, 422 geçersiz alan, 429 limit).

## Belgeler

- [OpenAPI şeması](https://sosyotrend.com/api/v2/openapi.json): tüm uçlar, makine tarafından okunur
- [Geliştirici sayfası](https://sosyotrend.com/gelistirici/): insanlar için örneklerle anlatım

## Uçlar

### GET /api/v2/ben/

Kimlik doğrulanan üye ve site. Anahtarın hangi üye ve siteye ait olduğunu döner. Bağlantıyı test etmek için ilk çağrı.

### GET /api/v2/kategoriler/

Sitenin kategorileri. Düz liste: id, adi, ust_id (0 = kök).

### GET /api/v2/haberler/

Son haberlerim. Bu sitedeki taslak ve yayındaki haberlerin (en yeniden). Sorgu: limit (en fazla 100).

### POST /api/v2/haberler/

Yeni taslak oluştur. Tek çağrıda tam taslak: üst alanlar + gövde + kapak görseli. Haber TASLAK olarak oluşur.

Alanlar:
- `baslik` (string): Başlık (10–110 karakter önerilir, en fazla 160)
- `kisa_baslik` (string): Listelerde görünen kısa başlık (en fazla 80)
- `spot` (string): Başlığın altındaki özet, 1–2 cümle (en fazla 600)
- `listeturu` (string): Düzen: makale | maddeli | numarali | tersnumarali
- `tur` (string): Tür: normal | viral
- `kategoriler` (integer[]): Kategori kimlikleri (GET /kategoriler)
- `metin` (string): Makale gövdesi. HTML (p, h2, h3, b, i, ul/li, a) ya da boş satırla ayrılmış düz metin
- `bolumler` (object[]): Liste düzeni için bölümler: [{baslik, metin}] (metin düz metin)
- `kapak_url` (string): Kapak görseli adresi (https, JPG/PNG/GIF). İndirilip sitenin görsel sunucusuna yüklenir

Dönüş: 201 {haber}

### GET /api/v2/haberler/{id}/

Haberi getir. Editörün gördüğü tüm durum: alanlar, bölümler, görseller, yerleşim.

### PATCH /api/v2/haberler/{id}/

Haberi güncelle. Yalnız gönderilen alanlar yazılır.

Alanlar:
- `baslik` (string): Başlık (10–110 karakter önerilir, en fazla 160)
- `kisa_baslik` (string): Listelerde görünen kısa başlık (en fazla 80)
- `spot` (string): Başlığın altındaki özet, 1–2 cümle (en fazla 600)
- `listeturu` (string): Düzen: makale | maddeli | numarali | tersnumarali
- `tur` (string): Tür: normal | viral
- `kategoriler` (integer[]): Kategori kimlikleri (GET /kategoriler)
- `gorunen_tarih` (integer): Haberde görünen tarih (unix zamanı); yalnız site sahibi

### DELETE /api/v2/haberler/{id}/

Taslağı sil. Yalnız taslak durumundaki haber silinir.

### GET /api/v2/haberler/{id}/kontrol/

Yayın kontrolü. engel[] (yayını durdurur) ve uyari[] (eksik ama yayınlanabilir) listeleri.

### POST /api/v2/haberler/{id}/yayinla/

Yayınla. API anahtarıyla şu an KAPALI: API'den gelen haberler moderasyon katmanı açılana kadar taslak kalır ve site panelinden yayınlanır.

Dönüş: 403 moderasyon_bekliyor

### POST /api/v2/haberler/{id}/taslak/

Yayından kaldır. Haberi taslağa alır; manşet/anasayfa yerleşimleri kapanır.

### POST /api/v2/haberler/{id}/bolumler/

Bölüm ekle. Gövdeye yeni bölüm ekler (makalede ara başlıklı bölüm, listede madde).

Alanlar:
- `baslik` (string): Bölüm başlığı
- `metin` (string): Bölüm metni

Dönüş: 201 {id}

### PATCH /api/v2/haberler/{id}/bolumler/{bid}/

Bölümü güncelle.

Alanlar:
- `baslik` (string)
- `metin` (string)
- `aktif` (boolean): false = yayında gizli
- `numarasiz` (boolean): Numaralı listede numara verme

### DELETE /api/v2/haberler/{id}/bolumler/{bid}/

Bölümü sil.

### POST /api/v2/haberler/{id}/bolumler/sira/

Bölüm sırası. Bölüm kimliklerini istenen sırayla gönder.

Alanlar:
- `idler` (integer[]): Bölüm kimlikleri

### POST /api/v2/haberler/{id}/gorseller/

Görsel yükle. multipart/form-data (dosya alanı: dosya) ya da JSON {yer, url}. Makale içine görsel için yer=govde ile yükleyip dönen id ile metne (img:#id) yaz.

Alanlar:
- `yer` (string): kapak | manset | sag-manset | bolum | govde
- `url` (string): Görsel adresi (dosya yerine)
- `bolum_id` (integer): yer=bolum ya da govde için bölüm kimliği

Dönüş: 201 {gorsel}

### DELETE /api/v2/haberler/{id}/gorseller/{yer}/

Görseli kaldır. yer=bolum için sona bölüm kimliği ekle: /gorseller/bolum/{bid}

### POST /api/v2/haberler/{id}/yerler/

Yerleşim. Anasayfa/manşet/sürmanşet görünürlüğü; üyenin yetkisi gerekir. Taslakta açılan yer, haber yayınlanınca devreye girer.

Alanlar:
- `yer` (string): anasayfagos | surmangos | mansetgos | sagmangos | mansetmetgiz
- `acik` (boolean)

## Örnek

```bash
curl -X POST https://sosyotrend.com/api/v2/haberler/ \
  -H "Authorization: Bearer $HABERSELF_ANAHTAR" \
  -H "Content-Type: application/json" \
  -d '{
    "baslik": "Samsun'da yeni sahil parkı hizmete açıldı",
    "spot": "Atakum sahilindeki park yürüyüş yolu ve oyun alanlarıyla açıldı.",
    "metin": "<p>Park bugün düzenlenen törenle açıldı.</p><h2>Neler var?</h2><p>…</p>",
    "kategoriler": [3],
    "kapak_url": "https://ornek.com/park.jpg"
  }'
```