Geliştirici API

Etkinlik ve profil verilerini kendi sitenize, uygulamanıza ya da raporlarınıza alın. Yanıtlar JSON'dur.

Genel kurallar

Temel adres: https://kulturvesanatdunyamiz.com.tr/api/v1
Herkese açık uç noktalar anahtar gerektirmez ve yalnızca yayındaki içeriği döner. Tarayıcıdan (CORS) çağrılabilir.
Hız sınırı: dakikada 120 istek (anahtar ya da IP başına). Aşılırsa 429 döner.
Tarihler Türkiye saatiyle (UTC+3), ISO 8601 biçimindedir.

Herkese açık uç noktalar

`GET /api/v1/events`	Yaklaşan etkinlikler. Parametreler: `q` (arama), `city` (il kimliği), `branch`, `from`, `to`, `page`, `pageSize` (en çok 100).
`GET /api/v1/events/{slug}`	Etkinlik ayrıntısı (konum, bilet türü, kalan kontenjan, düzenleyen).
`GET /api/v1/profiles/{slug}`	Sanatçı / topluluk özeti.
`GET /api/v1/cities`	81 il: koordinat, profil ve yaklaşan etkinlik sayıları.

curl "https://kulturvesanatdunyamiz.com.tr/api/v1/events?q=koro&pageSize=5"

Anahtarlı uç noktalar (Kurumsal paket)

Anahtarı Panel › Mini Site › 🔌 API sayfasından oluşturun ve X-Api-Key başlığıyla gönderin (ya da Authorization: Bearer …). Anahtar yalnızca kendi profilinizin verisine erişir. Paketiniz Kurumsal'dan düşerse anahtar çalışmaz.

`GET /api/v1/me/events`	Tüm etkinlikleriniz (taslak, geçmiş ve iptal dahil).
`GET /api/v1/me/events/{slug}/attendees`	Etkinliğin bilet listesi: bilet no, ad, e-posta, durum, tutar, giriş zamanı.

curl -H "X-Api-Key: sy_…" "https://kulturvesanatdunyamiz.com.tr/api/v1/me/events"

Katılımcı listesi kişisel veri içerir: KVKK kapsamında yalnızca etkinlik düzenleme amacıyla kullanın ve anahtarı güvenli saklayın.

Web kancaları

Seçtiğiniz olaylarda adresinize POST ile JSON gönderilir:

ticket.purchased — ücretsiz bilet alındı ya da ücretli biletin ödemesi onaylandı
event.published — etkinlik yayına alındı
event.cancelled — etkinlik iptal edildi (neden dahil)

{
  "id": "evt_5f0c…",
  "type": "ticket.purchased",
  "created": 1790000000,
  "data": { "ticketNumber": "SY-…", "attendeeName": "…", "attendeeEmail": "…", "price": 150.0,
            "eventSlug": "bahar-konseri", "eventTitle": "Bahar Konseri", "eventStartsAt": "…", "purchasedAt": "…" }
}

İmza doğrulama

Her istekte X-SanatYurdu-Signature: t=<unix zaman>,v1=<imza> başlığı vardır. İmza, kancanın imza anahtarıyla t + "." + gövde metninin HMAC-SHA256 (onaltılık) değeridir. Gövdeyi ham haliyle doğrulayın ve 5 dakikadan eski zaman damgalarını reddedin.

// Node.js
const crypto = require('crypto');
function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map(p => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}