API Referansı: RESTful Endpoints, Rate Limit

Q: Webhook ne zaman gelecek?

Webhook desteği Q4 2026 yol haritasındadır. Şu an mevcut değildir; planlanan event tipleri ileride duyurulacaktır.

Q: Rate limit aşılırsa ne olur?

429 Too Many Requests döner. Retry-After header'ı kaç saniye beklemeniz gerektiğini belirtir. Burst protection için exponential backoff önerilir.

Başlarken

Base URL ve Authentication

Tüm API çağrıları aşağıdaki temel URL üzerinden HTTPS ile yapılır. HTTP istekleri 301 yönlendirmesiyle HTTPS'e aktarılır.

Base URL

https://erisilebilircerez.com/api/v1

Authentication: Bearer Token

API key'inizi Authorization header'ında Bearer prefix'i ile gönderin. API key'inizi admin panel > Kurulum sayfasından alabilirsiniz.

curl https://erisilebilircerez.com/api/v1/banner/YOUR_API_KEY \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json"

Güvenlik uyarısı: Secret key'inizi asla browser taraflı kodda veya herkese açık repolarda paylaşmayın. Yalnızca güvenli sunucu ortamlarında kullanın.

GET

`/api/v1/banner/{api_key}`

Domain için aktif banner konfigürasyonunu döner. SDK her sayfa yüklenmesinde bu endpoint'i çağırır; yanıt sunucu tarafında 5 dakika önbelleğe alınır.

Path Parametresi

Parametre	Tip	Açıklama
`api_key`	string	Domain'inize ait herkese açık API key (zorunlu)

Query Parametreleri (opsiyonel)

Parametre	Tip	Açıklama
`lang`	string	`tr` \| `en` \| `de` (banner dili; varsayılan: domain ayarı)
`preview`	boolean	`true` ise consent cookie'si yazılmaz (Banner Builder canlı test için)

Örnek İstek

curl https://erisilebilircerez.com/api/v1/banner/pk_live_abc123 \
  -H "Authorization: Bearer sk_live_xyz789"

const response = await fetch(
    'https://erisilebilircerez.com/api/v1/banner/pk_live_abc123',
    { headers: { 'Authorization': 'Bearer sk_live_xyz789' } }
);
const banner = await response.json();

$response = Http::withToken('sk_live_xyz789')
    ->get('https://erisilebilircerez.com/api/v1/banner/pk_live_abc123');
$banner = $response->json();

Başarılı Yanıt 200 OK

{
  "success": true,
  "data": {
    "domain": "example.com",
    "position": "bottom",
    "theme": "modern",
    "language": "tr",
    "texts": {
      "title": "Çerez Tercihleriniz",
      "description": "Sitemiz deneyiminizi iyileştirmek için çerez kullanır...",
      "accept_all": "Tümünü Kabul Et",
      "reject_all": "Tümünü Reddet"
    },
    "categories": [
      { "id": "necessary", "required": true },
      { "id": "analytics", "required": false },
      { "id": "marketing", "required": false }
    ],
    "consent_expiry_days": 180,
    "products": { "cookie": true, "accessibility": false }
  }
}

POST

`/api/v1/consent/log`

Kullanıcının onay kararını sunucuya kaydeder. KVKK ve GDPR ispat yükümlülüğü için kayıt 90 gün saklanır.

Body Parametreleri (JSON)

Parametre	Tip	Açıklama
`api_key`	string	Herkese açık API key (zorunlu)
`session_id`	string	Anonim kullanıcı session ID'si (zorunlu)
`categories`	object	`{ necessary, analytics, marketing, functional }` (boolean değerler)
`action`	string	`accept_all` \| `reject_all` \| `custom`
`page_url`	string	Banner'ın gösterildiği sayfa URL'si
`user_agent`	string	Otomatik alınır; manuel göndermek opsiyoneldir

Örnek İstek

curl -X POST https://erisilebilircerez.com/api/v1/consent/log \
  -H "Authorization: Bearer sk_live_xyz789" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "pk_live_abc123",
    "session_id": "sess_a1b2c3d4",
    "categories": { "necessary": true, "analytics": true, "marketing": false },
    "action": "custom",
    "page_url": "https://example.com/products/123"
  }'

Yanıt 201 Created

{
  "success": true,
  "consent_id": "<string consent ID>",
  "timestamp": "2026-05-31T14:23:11+03:00",
  "expires_at": "2026-11-27T14:23:11+03:00"
}

POST

`/api/v1/heartbeat`

Pageview sayacını artırır ve domain'in etkin olduğunu işaretler. SDK her sayfa açılışında bu endpoint'i bir kez çağırır.

Body Parametreleri

Parametre	Tip	Açıklama
`api_key`	string	Herkese açık API key
`session_id`	string	Session ID (tekil pageview takibi için)
`page_url`	string	Aktif sayfa URL'si
`referrer`	string	`document.referrer` değeri (opsiyonel)

Yanıt

{
  "success": true,
  "pageview_count_month": 42183,
  "plan_limit": 100000,
  "usage_percent": 42.18
}

Rate Limiting

İstek Sınırları

Her IP adresi için uygulanır. Sınır aşımında yanıt, bekleme süresini gösteren bir header ile birlikte döner.

500

istek / dakika / IP

5 dk

banner önbellek süresi

90 gün

API log saklama süresi

Sınır aşımı: 429 Too Many Requests döner. Retry-After header'ı saniye cinsinden bekleme süresini belirtir. Burst protection için exponential backoff (1s, 2s, 4s, 8s...) önerilir. Enterprise planında özel rate limit artışı için satış ekibiyle görüşün.

Hata Kodları

HTTP Durum Kodları

Kod	Açıklama	Tipik Neden
200	OK	İstek başarılı
201	Created	Kayıt oluşturuldu (consent log)
401	Unauthorized	Bearer token eksik veya geçersiz
403	Forbidden	IP whitelist dışı veya plan limiti aşıldı
404	Not Found	API key veya kaynak bulunamadı
422	Unprocessable	Doğrulama hatası; yanıttaki errors alanını inceleyin
429	Too Many Requests	Rate limit aşıldı (500/dk)
500	Server Error	Sunucu taraflı hata; destek ile iletişime geçin

Hata Yanıt Formatı

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key bulunamadı veya devre dışı",
    "details": { "field": "api_key" }
  }
}

Webhook

Olay Bildirimleri Q4 2026

Webhook desteği Q4 2026 yol haritasındadır; şu an mevcut değildir. Aşağıdaki event'ler planlanmaktadır. Duyurular için iletişime geçin.

consent.given

Kullanıcı onay verdiğinde tetiklenir

consent.rejected

Kullanıcı reddettiğinde tetiklenir

consent.updated

Tercihler değiştirildiğinde tetiklenir

scan.completed

Cookie taraması tamamlandığında tetiklenir

scan.failed

Tarama başarısız olduğunda tetiklenir

subscription.expired

Abonelik sona erdiğinde tetiklenir

pageview.limit_warning

Pageview kullanımı yüzde 80 eşiğini geçtiğinde tetiklenir

a11y.profile_used

Erişilebilirlik profili kullanıldığında tetiklenir

Sık sorulanlar

Aklınızdaki sorular

SDK ile API arasındaki fark nedir?

Kısa yanıt: SDK browser tarafında çalışır ve banner'ı otomatik render eder. API ise sunucudan sunucuya entegrasyon için tasarlanmıştır; özel dashboard, mobil uygulama veya sunucu taraflı consent loglama gibi senaryolarda kullanılır. Çoğu müşteri yalnızca SDK kullanır.

Batch endpoint var mı?

Kısa yanıt: Şu an batch endpoint yoktur. POST /api/v1/consent/log endpoint'i tek çağrı içindir. Batch destek Q4 2026 yol haritasındadır.

IP whitelist nasıl çalışır?

Kısa yanıt: Admin panel > Kurulum > IP Restriction toggle'ını açıp izinli IP'leri (CIDR notation desteklenir: 192.168.1.0/24) girin. Whitelist dışı isteklere 403 Forbidden döner. Browser tarafından gelen SDK istekleri her zaman kabul edilir.

Webhook ne zaman gelecek?

Kısa yanıt: Webhook desteği Q4 2026 yol haritasındadır ve şu an mevcut değildir. Planlanan event tipleri ve imzalama mekanizması ilerleyen tarihlerde duyurulacaktır.

Rate limit aşılırsa ne olur?

Kısa yanıt: 429 Too Many Requests döner. Retry-After header'ı kaç saniye beklemeniz gerektiğini belirtir. Burst protection için exponential backoff (1s, 2s, 4s, 8s...) önerilir. Enterprise planında özel rate limit yükseltilebilir.

RESTful API: Geliştiriciler için tam dokümantasyon

Base URL ve Authentication

Base URL

Authentication: Bearer Token

`/api/v1/banner/{api_key}`

Path Parametresi

Query Parametreleri (opsiyonel)

Örnek İstek

Başarılı Yanıt 200 OK

`/api/v1/heartbeat`

Body Parametreleri

Yanıt

İstek Sınırları

HTTP Durum Kodları

Hata Yanıt Formatı

Olay Bildirimleri Q4 2026

Aklınızdaki sorular

API'yi test etmek ister misiniz?