Geliştirici

Web siteniz için Etkinlik API'si

Grubunuzun herkese açık etkinliklerini kendi web sitenize ekleyin — basit bir HTTP isteğiyle, hesap ve API anahtarı olmadan.

Önce en önemlisi

•Herkese açık erişim, kimlik doğrulama gerekmez.
•CORS etkin, uç nokta doğrudan tarayıcıdan çalışır.
•Yanıtlar 5 dakika önbelleğe alınır, hız sınırı dakikada 60 istektir.
•Yalnızca web sitesi ayarlarında herkese açık gösterim için onayladığınız veriler sunulur.
•Herkese açık kullanımda, web sitemize bağlantı veren bir 'Powered by Theatilo' ibaresi zorunludur.

Powered by Theatilo — sitenizde ibare

API'yi herkese açık bir sayfada kullanıyorsanız lütfen https://www.theatilo.com adresine bağlantı veren görünür bir 'Powered by Theatilo' ibaresi ekleyin. Alt bilgide sade bir satır yeterlidir.

Bu karşılıklı bir denge: Etkinliklerinizi otomatik olarak başka sistemlere ekler, ikinci kez güncellemek zorunda kalmazsınız. Ancak her API isteği bizde sunucu yükü ve altyapı maliyeti doğurur — sitenizin ziyaretçisi arttıkça daha fazla kaynak bağlanır. Theatilo ise karşılığında küçük ibare sayesinde, yeni tiyatro gruplarına ulaşmamıza yardımcı olan biraz ilgi görür.

HTML

<a href="https://www.theatilo.com" target="_blank" rel="noopener">
  Powered by Theatilo
</a>

Önizleme

Uç nokta

Tek bir GET uç noktası, grubunuzun yaklaşan etkinliklerini döndürür. yerine herkese açık Theatilo web sitenizin URL slug'ını yazın.

Slug'ımı nerede bulurum?

Theatilo yönetim alanında herkese açık web sitenizin ayarlarını açın. Slug, URL'nin benzersiz kısmıdır; örneğin https://theatilo.com/w/meine-buehne adresinde 'meine-buehne'.

GET

https://backend.chorilo.com/api/public-websites/{slug}/embed-events

Görünürlüğü kontrol et

API, herkese açık web sitenizin görünürlük ayarlarına uyar. Web sitesinde gizlenen her şey API üzerinden de engellenir — açıkça istenmiş olsa bile.

Ana anahtar: show_events devre dışıysa API boş bir liste döndürür.

Etkinlik türleri: Yalnızca onaylanan türler sunulur. Engellenen türler için yapılan bir istek (örneğin konser gösterimi devre dışıyken types[]=concert) sessizce filtrelenir.

Ayar	İlgili tür
show_events	Ana anahtar (her şeyi kapatır)
show_rehearsals	`rehearsal`
show_concerts	`concert`, `church_service`
show_other_events	`event`
show_event_descriptions	Yanıttaki description alanını kontrol eder

Sorgu parametreleri

Tüm parametreler isteğe bağlıdır. Parametre olmadan uç nokta, web sitenizin varsayılan ayarlarına göre sıradaki etkinlikleri döndürür.

Ad	Tür	Varsayılan	Açıklama
limit	integer	5	Döndürülen etkinlik sayısı. En az 1, en fazla 100.
from	ISO 8601	şimdi	Zaman aralığının başlangıç anı. Geçmiş etkinlikler varsayılan olarak sunulmaz.
to	ISO 8601	—	Zaman aralığının bitiş anı.
types[]	array	izin verilenlerin tümü	Şu türlerden bir veya birkaçı: rehearsal, concert, event. Engellenen türler sessizce filtrelenir.
lang	string (2)	—	İki harfli dil kodu (de, en, fr, nl, es, sv, it, sl). Şu anda yanıt meta verisinde yankı olarak döndürülür.

Hız sınırı & Önbellek

Uç nokta, IP adresi başına dakikada 60 istekle sınırlıdır. Sınır aşılırsa sunucu HTTP 429 ile yanıt verir.

Yanıtlar sunucu tarafında 5 dakika önbelleğe alınır (parametre kombinasyonu başına). Yeni etkinlikler gerekirse kısa bir gecikmeyle görünür.

Hız sınırı

60 / min

IP adresi başına

Sunucu önbelleği

5 min

parametre kombinasyonu başına

Yanıt biçimi

Yanıt bir JSON nesnesidir. Her etkinlik yalnızca herkese açık alanları içerir — dahili açıklamalar, katılımcı verileri veya diğer hassas bilgiler asla sunulmaz.

events[] — id, title, type, location, start_time, end_time, has_ticket_sale, isteğe bağlı ticket_sale_url (bilet satışı etkinse) ve isteğe bağlı description içeren etkinlik listesi.
ensemble_name — Grubunun görünen adı.
theme_color — Web sitesi ayarlarındaki hex renk kodu.
language — Web sitenizin dil kodu.

description alanı yalnızca herkese açık açıklamayı içerir. Dahili etkinlik açıklaması hiçbir zaman yanıtın parçası değildir.

JSON

{
  "events": [
    {
      "id": 42,
      "title": "Sommerkonzert",
      "type": "concert",
      "location": "Stadthalle Musterstadt",
      "start_time": "2026-06-14T19:30:00+02:00",
      "end_time": "2026-06-14T21:30:00+02:00",
      "description": "Belediye binasının bahçesinde yıllık yaz konseri.",
      "has_ticket_sale": true,
      "ticket_sale_url": "https://www.chorilo.com/shop/tickets/42"
    }
  ],
  "ensemble_name": "Musterchor",
  "theme_color": "#6366f1",
  "language": "de"
}

Örnekler

API'yi farklı dillerden şöyle çağırırsınız. Örnek, yaklaşan en fazla 10 konseri ve diğer etkinlikleri yükler.

curl "https://backend.chorilo.com/api/public-websites/mein-chor/embed-events?limit=10&types[]=concert&types[]=event"

Durum kodları

Kod	Anlamı
200	Başarılı, etkinlikler events dizisinde.
404	Bu slug'a sahip web sitesi bulunamadı.
422	Geçersiz sorgu parametreleri (örneğin bilinmeyen tür veya from'dan önce gelen to).
429	Hız sınırı aşıldı, bir dakika sonra yeniden deneyin.

All public endpoints

These are the read-only public endpoints currently exposed. No authentication required. JSON responses only.

Method	Path	Description	Limit
GET	/api/tickets/events	List public concert events	90/min
GET	/api/tickets/events/{eventId}	Single event detail	90/min
GET	/api/public-websites/{slug}	Public ensemble website by slug	90/min
GET	/api/public-websites/{slug}/embed-events	Embeddable concert calendar	60/min
GET	/api/public-websites/{slug}/calendar.ics	Public events as iCal feed for calendar subscriptions	300/min
GET	/api/choir-associations/public	Public association directory	90/min

Rate-limit response headers

Every /api/* response carries rate-limit headers. They are exposed via Access-Control-Expose-Headers for cross-origin agents.

X-RateLimit-Limit — per-window quota
X-RateLimit-Remaining — remaining requests
Retry-After — seconds to wait (HTTP 429 only)

JSON error format (RFC 9457)

All /api/* errors return application/problem+json regardless of Accept header.

{
  "type":     "https://www.chorilo.com/api/errors/not-found",
  "title":    "Resource not found",
  "status":   404,
  "detail":   "...",
  "instance": "/api/tickets/events/99999999"
}

Validation errors (422) include an errors object mapping fields to messages.

Sorularınız mı var?

API ile ilgili teknik sorularınız için şuraya başvurun: support@theatilo.com