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

Base URL

https://cerez.io/api/v1

OpenAPI-3.1-Spezifikation

Maschinenlesbare OpenAPI-3.1-Definition aller Endpunkte. Importierbar in Postman, Insomnia, Codegeneratoren und interaktive Clients.

Authentifizierung: Öffentlicher 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-Parameter (JSON)

Beispielanfrage

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": "3f2b8c1e-9d4a-4b7e-a1c2-0e5f6a7b8c9d",
    "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: '3f2b8c1e-9d4a-4b7e-a1c2-0e5f6a7b8c9d',
    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': '3f2b8c1e-9d4a-4b7e-a1c2-0e5f6a7b8c9d',
    'action': 'partial',
    'categories_accepted': {'necessary': True, 'analytics': True, 'marketing': False}
  })

Antwort 200 OK

{ "status": "ok" }

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

Cookies und Einwilligung

Barrierefreiheit

TCF und Vendor List

IAB TCF ist für Kunden derzeit geschlossen: Der Endpunkt /tcf liefert enabled: false und es wird kein TC-String erzeugt. Für die IAB-Registrierung gibt es noch keinen Zeitplan.

Telemetrie und System

Antwort-Hüllen

Aus historischen Gründen verwenden SDK-Endpunkte unterschiedliche Antwort-Hüllen; diese Formen bleiben aus Gründen der Abwärtskompatibilität erhalten. Werten Sie Antworten gemäß der folgenden Tabelle aus.

API-Version

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-Spezifikation

Alle 18 SDK-Endpunkte in maschinenlesbarer Form (Postman-Import / Client-Generierung).

Base URL

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

Authentifizierung: 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"

Endpunkte

Erfolgreiche Antwort 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

Bei niederfrequenten Ereignissen wird ein signierter POST an Ihre registrierten Endpunkte gesendet: scan.completed, cookies.new_found, scan.error. Einwilligungsereignisse mit hohem Volumen werden nicht per Webhook gesendet.

Beispiel-Payload und -Header

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 }
}

Signaturprüfung (Empfängerseite)

Die Signatur wird aus dem Zeitstempel und dem Rohtext abgeleitet. Prüfen Sie mit einem zeitkonstanten Vergleich und stellen Sie sicher, dass der Zeitstempel nicht älter als 5 Minuten ist (Replay-Schutz).

// 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 (Betroffenenanfragen) KVKK m.11 / GDPR m.15-17

Hilft Ihnen, auf Auskunfts- und Löschanfragen zu den Daten eines Besuchers zu reagieren. Löschung = Anonymisierung: direkte Identifikatoren (visitor_id, external_id, user_agent, region) werden entfernt; der Einwilligungsnachweis (Aktion, Kategorien, TCF-String, Zeitstempel) bleibt ERHALTEN. Sie überprüfen die Identität des Besuchers.

Die Anonymisierung erfolgt zweistufig (Schutz vor versehentlicher Löschung)

# 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": "3f2b8c1e-9d4a-4b7e-a1c2-0e5f6a7b8c9d" }'
# -> { "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": "3f2b8c1e-9d4a-4b7e-a1c2-0e5f6a7b8c9d", "confirm_token": "..." }'
# -> { "data": { "dry_run": false, "affected_count": 3 } }

Ändert sich die Datensatzanzahl zwischen Vorschau und Anwendung, wird das Token ungültig (409). Zugriff und Löschung werden bei jedem erfolgreichen Aufruf im Audit-Protokoll erfasst. Dieses Werkzeug hilft Ihnen, Ihre Compliance-Pflichten zu erfüllen; wenden Sie sich für die rechtliche Gültigkeit an qualifizierten Rechtsbeistand.

OpenAPI-3.1-Spezifikation

Maschinenlesbare OpenAPI-3.1-Definition der Management-API (Postman/Codegen).