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

Base URL

https://cerez.io/api/v1

OpenAPI 3.1 Spesifikasyonu

Tüm endpoint'lerin makine-okunur OpenAPI 3.1 tanımı. Postman, Insomnia, kod üreteçleri ve interaktif istemcilerle içe aktarabilirsiniz.

Kimlik Doğrulama: Herkese Açık API Key

SDK API herkese açık (public) API key ile çalışır: GET isteklerinde URL yolunda, POST isteklerinde istek gövdesinde gönderilir. Bu anahtar tarayıcıdaki SDK tarafından kullanılır, istemci tarafında görünür olması normaldir. Authorization: Bearer header kullanılmaz. API key'inizi admin panel > Kurulum sayfasından alabilirsiniz.

curl https://cerez.io/api/v1/banner/YOUR_API_KEY

Body Parametreleri (JSON)

Örnek İstek

curl -X POST https://cerez.io/api/v1/consent/log \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "visitor_id": "vis_a1b2c3d4",
    "action": "partial",
    "categories_accepted": { "necessary": true, "analytics": true, "marketing": false },
    "device_type": "desktop"
  }'

await fetch('https://cerez.io/api/v1/consent/log', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' },
  body: JSON.stringify({
    api_key: 'YOUR_API_KEY',
    visitor_id: 'vis_a1b2c3d4',
    action: 'partial',
    categories_accepted: { necessary: true, analytics: true, marketing: false }
  })
});

import requests
requests.post('https://cerez.io/api/v1/consent/log',
  headers={'Accept': 'application/json'},
  json={
    'api_key': 'YOUR_API_KEY',
    'visitor_id': 'vis_a1b2c3d4',
    'action': 'partial',
    'categories_accepted': {'necessary': True, 'analytics': True, 'marketing': False}
  })

Yanıt 200 OK

{ "status": "ok" }

Not: Doğrulama hatalarında 422 dönmesi için isteğe Accept: application/json başlığı ekleyin.

Çerez ve Onay

Erişilebilirlik

TCF ve Vendor List

Telemetri ve Sistem

Yanıt Zarfları

SDK uç noktaları tarihsel nedenlerle farklı yanıt zarfları kullanır; geriye dönük uyumluluk için bu şekiller korunmaktadır. Ayrıştırırken aşağıdaki tabloya göre okuyun.

API Sürümü

Güncel API ve SDK sürümleri ile TCF/GVL meta verisini çalışma zamanında GET /api/v1/meta uç noktasından alabilirsiniz (public, salt-okunur).

GET /api/v1/meta

{
  "api_version": "1.0.0",
  "sdk_version": "2.6.2",
  "products": ["cookie", "accessibility"],
  "tcf": { "gvl_version": 123, "policy_version": 5 },
  "docs": "https://cerez.io/kaynaklar/api-referans"
}

OpenAPI 3.1 Spesifikasyonu

18 SDK uç noktasının tamamı makine-okunur biçimde (Postman içe aktarma / istemci üretimi).

Base URL

https://cerez.io/api/mgmt/v1

Kimlik Doğrulama: Bearer secret_key

Secret key'inizi Authorization: Bearer header'ında gönderin. Secret key'i admin panel > Kurulum > API'den alın ve YALNIZCA güvenli sunucu ortamında saklayın; istemci tarafına asla koymayın.

curl https://cerez.io/api/mgmt/v1/domain \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Uç Noktalar

Başarılı Yanıt 200 OK

GET /api/mgmt/v1/domain

{
  "data": {
    "id": 42,
    "site_name": "Örnek",
    "domain_url": "https://example.com",
    "products": ["cookie", "accessibility"],
    "subscriptions": [
      { "product": "cookie", "plan_slug": "cookie_pro", "status": "active" }
    ],
    "settings": { "kvkk_enabled": true, "consent_expiry_days": 180 }
  },
  "meta": { "api": "mgmt/v1", "generated_at": "2026-06-30T12:00:00+00:00" }
}

Webhooks HMAC-SHA256

Düşük frekanslı olaylar gerçekleştiğinde kayıtlı adreslerinize imzalı bir POST gönderilir: scan.completed, cookies.new_found, scan.error. Yüksek hacimli consent olayları webhook ile gönderilmez.

Örnek payload ve başlıklar

POST https://ornek.com/webhooks/cerez
X-Cerez-Event: scan.completed
X-Cerez-Timestamp: 1782475200
X-Cerez-Signature: sha256=3a7b...e0

{
  "event": "scan.completed",
  "created_at": "2026-06-30T12:00:00+00:00",
  "domain_id": 42,
  "data": { "total_cookies": 31, "new_cookies": 2 }
}

İmza doğrulama (alıcı taraf)

İmza, zaman damgası ve ham gövdeden üretilir. Doğrularken sabit-zamanlı karşılaştırma kullanın ve zaman damgasının 5 dakikadan eski olmadığını doğrulayın (tekrar saldırısı koruması).

// Node.js
const crypto = require('crypto');
const expected = 'sha256=' + crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(timestamp + '.' + rawBody)
  .digest('hex');
const ok = crypto.timingSafeEqual(
  Buffer.from(expected), Buffer.from(signatureHeader)
);

// PHP
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
$ok = hash_equals($expected, $signatureHeader);

DSAR (İlgili Kişi Talepleri) KVKK m.11 / GDPR m.15-17

Bir ziyaretçinin verisine erişim ve silme taleplerinize yanıt vermenize yardımcı olur. Silme = anonimleştirme: doğrudan tanımlayıcılar (visitor_id, external_id, user_agent, region) kaldırılır; consent ispat delili (action, kategoriler, TCF string, zaman damgaları) KORUNUR. Ziyaretçinin kimliğini siz doğrularsınız.

Anonimleştirme iki adımlıdır (kazara silme koruması)

# 1. Önizleme (confirm_token yok) — hiçbir şey değişmez
curl -X POST https://cerez.io/api/mgmt/v1/dsar/erasure \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "visitor_id": "vis_a1b2c3" }'
# -> { "data": { "dry_run": true, "matched_count": 3, "confirm_token": "..." } }

# 2. Uygula (önizlemeden gelen confirm_token ile)
curl -X POST https://cerez.io/api/mgmt/v1/dsar/erasure \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "visitor_id": "vis_a1b2c3", "confirm_token": "..." }'
# -> { "data": { "dry_run": false, "affected_count": 3 } }

Önizleme ile uygulama arasında kayıt sayısı değişirse token geçersiz olur (409). Erişim ve silme her başarılı çağrıda denetim günlüğüne yazılır. Bu araç uyum yükümlülüklerinizi yerine getirmenize yardımcı olur; hukuki geçerlilik için nitelikli danışmanınıza başvurun.

OpenAPI 3.1 Spesifikasyonu

Management API'nin makine-okunur OpenAPI 3.1 tanımı (Postman/codegen).