Kayıt API'si

Onay kayıtlarınızı kendi sistemlerinize (veri ambarı, CRM, analitik) çekin. Sunucu-sunucu, site API anahtarıyla doğrulanır. Tasarımdan gizlilik: ham IP/UA saklanmaz.

Base URLhttps://consent.basework.studio

Genel bakış

Tek bir uç nokta vardır: GET /api/v1/consents. Kayıtları JSON ya da CSV olarak döndürür; tarihe göre filtreler ve cursor ile sayfalar. Kayıtlar en eskiden yeniye sıralanır, böylece artımlı senkron kolaydır.

Kimlik doğrulama

Her istekte sitenizin API anahtarını gönderin. Anahtarı panelde sitenizin Ayarlar sekmesindeki “API anahtarı” alanında bulursunuz. Bir sır olarak saklayın — yalnızca sunucu tarafında kullanın, tarayıcıya koymayın (bu yüzden CORS kapalıdır).

Authorization: Bearer <API_KEY>
# veya
X-Api-Key: <API_KEY>

Uç nokta

GET https://consent.basework.studio/api/v1/consents

Parametreler

Parametre	Tip	Açıklama
from	YYYY-MM-DD	Başlangıç tarihi (dahil), createdAt'e göre.
to	YYYY-MM-DD	Bitiş tarihi (dahil).
cursor	string	Son alınan kaydın id'si. Yalnızca daha yeni kayıtları döndürür — artımlı senkron için.
limit	number	Sayfa boyutu. Varsayılan 100, en fazla 1000.
format	json \| csv	Yanıt biçimi. Varsayılan json.

Yanıt

JSON yanıtı bir data dizisi ve bir nextCursor içerir:

{
  "data": [
    {
      "createdAt": "2026-07-22T21:25:00.000Z",
      "consentId": "1ae99ad3-c8bf-44c0-824d-16531cb5a94d",
      "policyVersion": "1",
      "categories": { "necessary": true, "analytics": true, "marketing": false },
      "consentHash": "87d184e9b2078574a9d31605040c700f8b6c430faacd33513f615b8548789ba9"
    }
  ],
  "nextCursor": "146"
}

createdAt	Onayın alındığı an. ISO 8601, UTC.
consentId	İstemci tarafından üretilen benzersiz UUID (idempotency anahtarı).
policyVersion	Onayın verildiği politika sürümü.
categories	Kategori → boolean eşlemesi. necessary her zaman true.
consentHash	PII içermeyen, kurcalanmaya dayanıklı sha256 makbuz.
nextCursor	Sonraki sayfa için cursor. null ise son sayfadasınız.

format=csv ile aynı alanlar CSV olarak döner (sütunlar: createdAt, consentId, policyVersion, necessary, analytics, marketing, consentHash). Sayfalama cursor'ı CSV'de X-Next-Cursor başlığıyla verilir.

Sayfalama & artımlı senkron

Her yanıttaki nextCursor değerini bir sonraki isteğin cursor parametresine verin. Kayıtlar bittiğinde nextCursor null olur. Son cursor'ı kalıcı olarak saklayın; bir sonraki senkronda onu vererek yalnızca yeni kayıtları çekersiniz. Tüm geçmişi almak için cursor'sız başlayın.

Örnekler

Tüm kayıtlar (ilk sayfa)

curl -H "Authorization: Bearer $API_KEY" \
  "https://consent.basework.studio/api/v1/consents?limit=500"

Sonraki sayfa / yeni kayıtlar

curl -H "Authorization: Bearer $API_KEY" \
  "https://consent.basework.studio/api/v1/consents?cursor=146"

CSV, tarih aralığıyla

curl -H "Authorization: Bearer $API_KEY" \
  "https://consent.basework.studio/api/v1/consents?format=csv&from=2026-07-01" -o consents.csv

Node.js — artımlı senkron döngüsü

const API_KEY = process.env.BW_API_KEY;
const BASE = "https://consent.basework.studio/api/v1/consents";

// cursor'ı kalıcı sakla; her çalıştırmada kaldığın yerden devam et.
async function sync(startCursor) {
  let cursor = startCursor;
  for (;;) {
    const url = new URL(BASE);
    url.searchParams.set("limit", "500");
    if (cursor) url.searchParams.set("cursor", cursor);

    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${API_KEY}` },
    });
    if (!res.ok) throw new Error(`API ${res.status}`);

    const { data, nextCursor } = await res.json();
    for (const row of data) await saveConsent(row); // kendi sistemine yaz

    if (!nextCursor) return cursor; // en son cursor'ı sakla
    cursor = nextCursor;
  }
}

Python — artımlı senkron döngüsü

import os, requests

API_KEY = os.environ["BW_API_KEY"]
BASE = "https://consent.basework.studio/api/v1/consents"

def sync(cursor=None):
    while True:
        params = {"limit": 500}
        if cursor:
            params["cursor"] = cursor
        r = requests.get(
            BASE,
            headers={"Authorization": f"Bearer {API_KEY}"},
            params=params,
        )
        r.raise_for_status()
        body = r.json()
        for row in body["data"]:
            save_consent(row)  # kendi sistemine yaz
        cursor = body["nextCursor"]
        if not cursor:
            return cursor  # sakla, sonraki çalıştırmada geç

Hata kodları

HTTP	error	Açıklama
401	missing_api_key	Authorization / X-Api-Key başlığı yok.
401	invalid_api_key	Anahtar geçersiz ya da site devre dışı.
429	rate_limited	IP başına dakikalık limit aşıldı. Retry-After başlığına bakın.

Rate limit: IP başına dakikada 120 istek. Aşılırsa 429 ve Retry-After (saniye) döner.

Gizlilik & güvenlik

Ham IP adresi ve User-Agent hiçbir zaman saklanmaz veya döndürülmez.
Her kayıt PII içermez; consentHash kurcalamaya karşı kanıt sağlar.
API anahtarı bir sırdır — sunucu tarafında tutun, istemci/tarayıcı koduna koymayın.
Anahtar sızarsa panelden siteyi düzenleyip yeni anahtar üretebilirsiniz (destek ile).