Adil Kullanım ve API Limitleri

Sosyal Köprü API, tüm kullanıcılara adil ve öngörülebilir bir hizmet sunmak için birbirini tamamlayan üç ayrı limit katmanı kullanır. Bu katmanlar farklı şeyleri ölçer ve birbirinden bağımsız işler:

Plan Bazında Limitler

1. Aylık Gönderi Kotası

Aylık gönderi kotası (maxMonthlyPosts), belirli bir 30 günlük dönemde kaç gönderi paylaşabileceğinizin üst sınırıdır.

• Sayım birimi: kompozisyon başına 1. Bir gönderiyi kaç platforma/hesaba yayınladığınızdan bağımsız olarak 1 gönderi sayılır. 5 hesaba aynı anda yayınlanan bir gönderi kotadan yalnızca 1 düşer.
• Ortak sayaç: Kota, hem panel (dashboard) hem de API üzerinden yapılan paylaşımlarda aynı sayaçtan düşer.
• Taslaklar sayılmaz: status: "draft" ile oluşturulan gönderiler kotayı tüketmez; yalnızca yayınlanacak (anında veya planlı) gönderiler sayılır.
• İptal iade eder: Henüz yayınlanmamış (planlı) bir gönderiyi yayından önce iptal/silerseniz kota slotu geri verilir.

Kota dolduğunda ne olur?

Aylık gönderi kotanız dolduğunda POST /v1/posts kredi tüketmeden reddedilir:

{
  "success": false,
  "error": {
    "code": "POST_QUOTA_EXCEEDED",
    "message": "Bu ay için planınızın gönderi kotasına ulaştınız. Kota bir sonraki döngüde sıfırlanır. API krediniz, paylaşım dışındaki işlemler (okuma, analitik, medya) için kullanılmaya devam edebilir.",
    "details": {},
    "docsUrl": "https://docs.sosyalkopru.com/errors/post-quota-exceeded"
  }
}

Önemli davranış: Yayın engellenir ama krediniz tükenmez. Kotanız dolduktan sonra bile kalan kredinizi paylaşım dışı işlemler için kullanmaya devam edebilirsiniz:

• ✅ GET /v1/analytics/* — analitik okuma
• ✅ GET /v1/posts, GET /v1/accounts — veri listeleme
• ✅ POST /v1/media/upload/* — medya yükleme
• ✅ PATCH / DELETE /v1/posts/{id} — mevcut gönderileri düzenleme/iptal
• ❌ POST /v1/posts (yayın) — engellenir

2. Kredi Sistemi

Kredi, tüm API operasyonlarının ortak aylık bütçesidir. Ayrıntılı endpoint maliyet tablosu için Kredi Sistemi sayfasına bakın. Özet:

• Yayın: hedef hesap sayısı × 2 kredi (anında/planlı aynı).
• Okuma/liste: 1 kredi. Analitik: 3 kredi. Medya: 2 kredi.
• Başarısız isteklerde rezerve edilen kredi iade edilir.

3. Rate Limit

Rate limit, kısa süreli istek yoğunluğunu sınırlar (bkz. Rate Limiting). Dakika, saat ve gün pencerelerinden herhangi biri aşılırsa 429 döner. Günlük rate limit, planınızın aylık kredisine eşittir; böylece rate limit ile kredi birbiriyle uyumludur.

Katmanların Birlikte Çalışması — Senaryolar

Aşağıdaki senaryolar üç katmanın gerçek durumlarda nasıl etkileştiğini gösterir.

Senaryo A — Light plan, yoğun yayın ayı

Bir kullanıcı Başlangıç (Light) planında, her biri 3 platforma yayınlanan gönderiler paylaşıyor:

• Her gönderi: kotadan 1, krediden 3 × 2 = 6 düşer.
• 400 gönderiye ulaştığında kota dolar → yeni yayın 403 POST_QUOTA_EXCEEDED.
• Bu noktada tüketilen kredi ≈ 400 × 6 = 2.400 (toplam 6.000’in altında).
• Kalan ~3.600 kredi ile analitik, listeleme ve medya işlemlerine devam edebilir.

Senaryo B — Moderate plan, tek platforma yüksek hacim

Büyüme (Moderate) planında kota sınırsızdır; bağlayıcı sınır kredidir:

• Her gönderi tek platforma: 2 kredi.
• 18.000 kredi ile teorik olarak ~9.000 tek-platform yayın yapılabilir (okuma/analitik payı düştükçe azalır).
• Kredi biterse 402 INSUFFICIENT_CREDITS; döngü sıfırlanınca yeniden dolar.

Senaryo C — Toplu içe aktarma (burst)

Kısa sürede çok sayıda istek atan bir entegrasyon:

• Dakikada plan limitini (ör. Light 60) aşarsa 429 alır ve X-RateLimit-Reset süresi kadar bekler.
• Krediniz ve kotanız yeterli olsa bile rate limit devreye girer — bu, ani yük ve retry fırtınalarına karşı korumadır.

Senaryo D — Başarısız istek

• Kredi işlem başlamadan önce rezerve edilir.
• İşlem 4xx/5xx ile sonuçlanırsa rezerve kredi iade edilir, kota sayacı (yayın oluşmadıysa) geri verilir.
• Yani başarısız istekler bütçenizi kalıcı olarak tüketmez.

Döngü Sıfırlama

• Kredi havuzu: İlk anahtar oluşturma tarihinizden itibaren 30 günlük döngülerle yenilenir. Kullanımınızın %80’ine ulaştığınızda uyarı e-postası gönderilir.
• Aylık gönderi kotası: Çalışma alanı bazında 30 günlük döngüyle sıfırlanır.

Sandbox ile Test

sk_test_ önekli sandbox anahtarları gerçek yayın yapmaz ve limitlerin %10’u ile çalışır (kredi maliyetleri ve rate limitler). Entegrasyonunuzu, üretim kotanızı harcamadan sandbox’ta doğrulayabilirsiniz. Bkz. Sandbox Modu.

Adil Kullanım İlkeleri

API’yi aşağıdaki ilkelere uygun kullanmanızı bekliyoruz:

1. Retry’leri kontrol edin. 429 ve 5xx yanıtlarında X-RateLimit-Reset’e uyan exponential back-off kullanın; sıkı döngülerde yeniden denemeyin.
2. Gereksiz fan-out’tan kaçının. Bir gönderiyi yalnızca ilgili hesaplara yayınlayın — hem kredi hem de platform kalitesi için.
3. Veriyi önbelleğe alın. Sık okunan analitik/hesap verilerini kendi tarafınızda önbelleğe alın.
4. Anahtar güvenliği. Anahtarlarınızı sızdırmayın; şüpheli aktivite (5 dk’da 500+ istek) otomatik izlenir ve bildirilir. Gerekirse sk_live_ anahtarını iptal edip yeniden oluşturun.