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

Base URL

https://cerez.io/api/v1

OpenAPI 3.1 Specification

Machine-readable OpenAPI 3.1 definition of all endpoints. Import it into Postman, Insomnia, code generators and interactive clients.

Authentication: Public 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 Parameters (JSON)

Example Request

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

Response 200 OK

{ "status": "ok" }

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

Cookies and Consent

Accessibility

TCF and Vendor List

IAB TCF is currently closed to customers: the /tcf endpoint returns enabled: false and no TC String is produced. No timeline has been set for IAB registration.

Telemetry and System

Response Envelopes

For historical reasons, SDK endpoints use different response envelopes; these shapes are preserved for backward compatibility. Parse responses according to the table below.

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 Specification

All 18 SDK endpoints in machine-readable form (Postman import / client generation).

Base URL

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

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

Endpoints

Successful Response 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

When low-frequency events occur, a signed POST is sent to your registered endpoints: scan.completed, cookies.new_found, scan.error. High-volume consent events are not sent via webhook.

Example payload and headers

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

Signature verification (receiver side)

The signature is derived from the timestamp and the raw body. Verify with a constant-time comparison and confirm the timestamp is not older than 5 minutes (replay protection).

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

Helps you respond to access and erasure requests for a visitor's data. Erasure = anonymization: direct identifiers (visitor_id, external_id, user_agent, region) are removed; consent proof (action, categories, TCF string, timestamps) is PRESERVED. You verify the visitor's identity.

Anonymization is two-step (accidental-deletion protection)

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

If the record count changes between preview and apply, the token becomes invalid (409). Access and erasure are written to the audit log on every successful call. This tool helps you meet your compliance obligations; consult qualified counsel for legal validity.

OpenAPI 3.1 Specification

Machine-readable OpenAPI 3.1 definition of the Management API (Postman/codegen).