Kredi Sistemi

Sosyal Köprü API, istek başına sabit ücret yerine kredi tabanlı bir kota sistemi kullanır. Her plan belirli miktarda aylık kredi içerir; API üzerinden yapılan her işlem bu havuzdan kredi tüketir.

Krediler hesabınıza (kullanıcı) bağlı ortak bir havuzda tutulur — bir API anahtarını silip yenisini oluşturmak bakiyenizi sıfırlamaz. Havuz 30 günlük döngülerle yenilenir (takvim ayı değil).

Plan Kredileri

API Yoğunluğu	Plan	Aylık Kredi	Aktif Anahtar
Light	Başlangıç	6.000	1
Moderate	Büyüme	18.000	3
Heavy	Ajans Pro	45.000	5

Ücretsiz Deneme (trial) planında public API erişimi yoktur (0 kredi, 0 anahtar).

Endpoint Kredi Maliyetleri

Yayın maliyeti, yapılan gerçek işe (kaç hedef hesaba gönderildiğine) göre hesaplanır. Bir gönderiyi kaç platforma/hesaba yayınlıyorsanız o kadar iş yapılır.

İşlem	Endpoint	Maliyet
Veri listeleme / okuma	`GET` (tüm endpoint’ler)	1 kredi
Gönderi yayınlama	`POST /v1/posts`	hedef hesap sayısı × 2 kredi
Taslak oluşturma	`POST /v1/posts` (`status: "draft"`)	1 kredi
Gönderi güncelleme	`PATCH /v1/posts/{id}`	1 kredi
Gönderi iptal / silme	`DELETE /v1/posts/{id}`	1 kredi
Gönderi kopyalama	`POST /v1/posts/{id}/duplicate`	2 kredi
Toplu işlem	`POST /v1/posts/bulk`	etkilenen gönderi başına 1 kredi
Medya yükleme (tamamlama)	`POST /v1/media/upload/complete`	2 kredi
Medya presign (imzalı URL)	`POST /v1/media/upload/presign`	Ücretsiz
Analitik verileri	`GET /v1/analytics/*`	3 kredi
Webhook testi	`POST /v1/webhooks/{id}/test`	Ücretsiz
API meta bilgisi	`GET /v1/me`	Ücretsiz

Anında ve planlı yayın aynı ücrete tabidir. Maliyet yalnızca hedef hesap sayısına bağlıdır; gönderiyi ileri tarihe planlamak krediyi ucuzlatmaz. Böylece fiyatlandırma yapılan işe adil şekilde bağlıdır.

Yayın maliyeti örnekleri

Senaryo	Hedef hesap	Maliyet
Tek platforma gönderi (yalnız Instagram)	1	2 kredi
3 platforma aynı gönderi (IG + X + LinkedIn)	3	6 kredi
7 platforma fan-out	7	14 kredi

Tek istekte hedeflenebilecek maksimum hesap sayısı 50 ile sınırlıdır; daha büyük fan-out’lar reddedilir.

Sandbox modunda (sk_test_) tüm maliyetler %10 olarak uygulanır (en az 1 kredi). Örneğin 3 hesaba yayın (6 kredi) sandbox’ta 1 kredi harcar.

Gönderi Kotası ≠ Kredi

Kredi bütçesi ile aylık gönderi kotası (maxMonthlyPosts) birbirinden bağımsız iki sınırdır:

Kredi = tüm API operasyonlarının (okuma, analitik, medya, yayın) ortak bütçesi.
Aylık gönderi kotası = kaç gönderi paylaşabileceğinizin üst sınırı (kompozisyon başına 1 sayılır; kaç hesaba gönderdiğinizden bağımsız).

Kotanız dolduğunda yeni yayın engellenir ancak kalan krediniz paylaşım dışı işlemler için kullanılabilir kalır. Ayrıntılar için Adil Kullanım ve API Limitleri sayfasına bakın.

Yetersiz Kredi Hatası

Kredi bakiyeniz işlemin maliyetini karşılamıyorsa API 402 Payment Required döner:


{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "API kredi bakiyeniz yetersiz. Kredi kullanımınızı kontrol edin veya döngü sıfırlanmasını bekleyin.",
    "details": {},
    "docsUrl": "https://docs.sosyalkopru.com/errors/insufficient-credits"
  }
}

Kredi, işlem başlamadan önce atomik olarak rezerve edilir. İşlem hata ile sonuçlanırsa (4xx/5xx) rezerve edilen kredi otomatik iade edilir — başarısız istekler kredinizi tüketmez.

Kullanım Durumunu İzleme

Güncel kredi bakiyenizi ve dönem istatistiklerinizi /v1/usage endpoint’i ile sorgulayabilirsiniz (bu çağrı ücretsizdir):


curl -X GET https://api.sosyalkopru.com/api/v1/usage \
  -H "Authorization: Bearer sk_live_..."


{
  "success": true,
  "data": {
    "apiKey": {
      "id": "key_...",
      "name": "Üretim Anahtarı",
      "planTier": "growth",
      "apiTier": "moderate",
      "creditBalance": 8157,
      "totalRequests": 48213
    },
    "currentMonth": {
      "requests": 2891,
      "creditsUsed": 1843,
      "periodStart": "2026-07-01T00:00:00.000Z",
      "periodEnd": "2026-07-31T23:59:59.000Z"
    },
    "topEndpoints": [{ "endpoint": "/api/v1/posts", "requests": 1204 }],
    "recentRequests": []
  }
}

Kredi Optimizasyon İpuçları

Gerekmedikçe az hesaba yayın yapın: Yayın maliyeti hedef hesap sayısıyla ölçeklenir. Bir kampanyayı yalnızca ilgili platformlara göndererek kredi tasarrufu sağlayın.

Toplu işlemleri tercih edin: Çok sayıda planlı gönderiyi yeniden zamanlamak/iptal etmek için POST /v1/posts/bulk kullanın — tek tek PATCH/DELETE yerine tek istekte, etkilenen gönderi başına 1 kredi.

Analitiği önbelleğe alın: Sık okunan analitik verilerini kendi sisteminizde önbelleğe alarak tekrar eden GET /v1/analytics/* çağrılarını azaltın (her biri 3 kredi).

Taslakları ücretsize yakın kullanın: İçeriği önce status: "draft" ile oluşturup (1 kredi) daha sonra yayınlayabilirsiniz.

Kredi tüketimi, işlem başarıyla tamamlandığında (HTTP < 400) kesinleşir ve audit log’a yazılır. Başarısız isteklerde rezerve edilen kredi iade edilir.