API-Referenz: RESTful-Endpoints, Rate Limit

Q: Wann kommen Webhooks?

Webhook-Unterstützung steht auf der Roadmap für Q4 2026. Sie ist noch nicht verfügbar; die geplanten Event-Typen werden später bekannt gegeben.

Q: Was passiert, wenn das Rate Limit überschritten wird?

Es wird ein 429 Too Many Requests zurückgegeben. Der Retry-After-Header gibt an, wie viele Sekunden Sie warten müssen. Für Burst Protection wird Exponential Backoff empfohlen.

Erste Schritte

Base URL und Authentication

Alle API-Aufrufe erfolgen über HTTPS über die untenstehende Base URL. HTTP-Anfragen werden per 301-Weiterleitung auf HTTPS umgeleitet.

Base URL

https://cerez.io/api/v1

Authentication: Bearer Token

Senden Sie Ihren API Key im Authorization-Header mit dem Bearer-Prefix. Ihren API Key erhalten Sie im Admin-Panel > Installation.

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

Sicherheitshinweis: Geben Sie Ihren Secret Key niemals in browserseitigem Code oder in öffentlichen Repositories weiter. Verwenden Sie ihn ausschließlich in sicheren Serverumgebungen.

GET

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

Gibt die aktive Banner-Konfiguration für eine Domain zurück. Das SDK ruft diesen Endpoint bei jedem Seitenaufruf auf; die Antwort wird serverseitig 5 Minuten zwischengespeichert.

Pfad-Parameter

Parameter	Typ	Beschreibung
`api_key`	string	Der öffentliche API Key Ihrer Domain (erforderlich)

Query-Parameter (optional)

Parameter	Typ	Beschreibung
`lang`	string	`tr` \| `en` \| `de` (Banner-Sprache; Standard: Domain-Einstellung)
`preview`	boolean	Bei `true` wird kein Consent-Cookie geschrieben (für Live-Tests im Banner Builder)

Beispielanfrage

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

const response = await fetch(
    'https://cerez.io/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://cerez.io/api/v1/banner/pk_live_abc123');
$banner = $response->json();

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

Speichert die Einwilligungsentscheidung des Nutzers auf dem Server. Der Datensatz wird 90 Tage aufbewahrt, um der Nachweispflicht nach KVKK und GDPR zu genügen.

Body-Parameter (JSON)

Parameter	Typ	Beschreibung
`api_key`	string	Öffentlicher API Key (erforderlich)
`session_id`	string	Anonyme Nutzer-Session-ID (erforderlich)
`categories`	object	`{ necessary, analytics, marketing, functional }` (boolesche Werte)
`action`	string	`accept_all` \| `reject_all` \| `custom`
`page_url`	string	Die URL der Seite, auf der das Banner angezeigt wurde
`user_agent`	string	Wird automatisch erfasst; manuelles Senden ist optional

Beispielanfrage

curl -X POST https://cerez.io/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"
  }'

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

Erhöht den Pageview-Zähler und markiert die Domain als aktiv. Das SDK ruft diesen Endpoint einmal pro Seitenaufruf auf.

Body-Parameter

Parameter	Typ	Beschreibung
`api_key`	string	Öffentlicher API Key
`session_id`	string	Session-ID (für eindeutiges Pageview-Tracking)
`page_url`	string	Aktuelle Seiten-URL
`referrer`	string	`document.referrer`-Wert (optional)

Antwort

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

Rate Limiting

Anfragelimits

Wird pro IP-Adresse angewendet. Bei Überschreitung des Limits enthält die Antwort einen Header mit der Wartezeit.

500

Anfragen / Minute / IP

5 dk

Banner-Cache-Dauer

90 gün

API-Log-Aufbewahrungsdauer

Limit überschritten: Es wird ein 429 Too Many Requests zurückgegeben. Der Retry-After-Header gibt die Wartezeit in Sekunden an. Für Burst Protection wird Exponential Backoff (1s, 2s, 4s, 8s...) empfohlen. Für eine individuelle Rate-Limit-Erhöhung im Enterprise-Plan wenden Sie sich an das Vertriebsteam.

Fehlercodes

HTTP-Statuscodes

Code	Beschreibung	Typische Ursache
200	OK	Anfrage erfolgreich
201	Created	Datensatz erstellt (Consent-Log)
401	Unauthorized	Bearer Token fehlt oder ist ungültig
403	Forbidden	Außerhalb der IP-Whitelist oder Plan-Limit überschritten
404	Not Found	API Key oder Ressource nicht gefunden
422	Unprocessable	Validierungsfehler; prüfen Sie das errors-Feld in der Antwort
429	Too Many Requests	Rate Limit überschritten (500/min)
500	Server Error	Serverseitiger Fehler; kontaktieren Sie den Support

Fehlerantwort-Format

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

Webhook

Ereignisbenachrichtigungen Q4 2026

Webhook-Unterstützung steht auf der Roadmap für Q4 2026; sie ist noch nicht verfügbar. Die folgenden Events sind geplant. Kontaktieren Sie uns für Ankündigungen.

consent.given

Wird ausgelöst, wenn der Nutzer einwilligt

consent.rejected

Wird ausgelöst, wenn der Nutzer ablehnt

consent.updated

Wird ausgelöst, wenn Einstellungen geändert werden

scan.completed

Wird ausgelöst, wenn ein Cookie-Scan abgeschlossen ist

scan.failed

Wird ausgelöst, wenn ein Scan fehlschlägt

subscription.expired

Wird ausgelöst, wenn ein Abonnement endet

pageview.limit_warning

Wird ausgelöst, wenn die Pageview-Nutzung die 80-Prozent-Schwelle überschreitet

a11y.profile_used

Wird ausgelöst, wenn ein Barrierefreiheitsprofil verwendet wird

Häufige Fragen

Ihre offenen Fragen

Was ist der Unterschied zwischen SDK und API?

Kurze Antwort: Das SDK läuft im Browser und rendert das Banner automatisch. Die API ist für die Server-zu-Server-Integration konzipiert; sie wird in Szenarien wie eigenen Dashboards, mobilen Apps oder serverseitigem Consent-Logging eingesetzt. Die meisten Kunden nutzen nur das SDK.

Gibt es einen Batch-Endpoint?

Kurze Antwort: Derzeit gibt es keinen Batch-Endpoint. Der Endpoint POST /api/v1/consent/log ist für Einzelaufrufe gedacht. Batch-Unterstützung steht auf der Roadmap für Q4 2026.

Wie funktioniert die IP-Whitelist?

Kurze Antwort: Aktivieren Sie den IP-Restriction-Toggle unter Admin-Panel > Installation und tragen Sie die erlaubten IPs ein (CIDR-Notation wird unterstützt: 192.168.1.0/24). Anfragen außerhalb der Whitelist erhalten ein 403 Forbidden. SDK-Anfragen aus dem Browser werden immer akzeptiert.

Wann kommen Webhooks?

Kurze Antwort: Webhook-Unterstützung steht auf der Roadmap für Q4 2026 und ist noch nicht verfügbar. Die geplanten Event-Typen und der Signaturmechanismus werden zu einem späteren Zeitpunkt bekannt gegeben.

Was passiert, wenn das Rate Limit überschritten wird?

Kurze Antwort: Es wird ein 429 Too Many Requests zurückgegeben. Der Retry-After-Header gibt an, wie viele Sekunden Sie warten müssen. Für Burst Protection wird Exponential Backoff (1s, 2s, 4s, 8s...) empfohlen. Im Enterprise-Plan kann das Rate Limit erhöht werden.

RESTful API: Vollständige Dokumentation für Entwickler

Base URL und Authentication

Base URL

Authentication: Bearer Token

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

Pfad-Parameter

Query-Parameter (optional)

Beispielanfrage

Erfolgreiche Antwort 200 OK

`/api/v1/heartbeat`

Body-Parameter

Antwort

Anfragelimits

HTTP-Statuscodes

Fehlerantwort-Format

Ereignisbenachrichtigungen Q4 2026

Ihre offenen Fragen

Möchten Sie die API testen?