Geliştiriciler
Entegrasyon API
Biletsa etkinliklerini kendi sitenizde, uygulamanızda ya da bilet platformunuzda listeleyin. Biletler Biletsa üzerinden satılır; sizin bağlantınızdan gelen satışlar platformunuza yazılır.
Nasıl çalışır
Anahtar alın
Bize yazın, platformunuz için bir API anahtarı oluşturalım. Anahtar yalnız bir kez gösterilir.
Etkinlikleri çekin
Satıştaki etkinlikleri, seansları, fiyatları ve kalan bilet sayısını JSON olarak alın.
Yönlendirin
Yanıttaki bağlantıyı kullanın. Satın alma Biletsa üzerinde tamamlanır, satış 30 gün boyunca size yazılır.
Kimlik doğrulama
Her istekte API anahtarınızı Authorization başlığında gönderin. Temel adres https://biletsa.com/api/v1.
curl https://biletsa.com/api/v1/etkinlikler \
-H "Authorization: Bearer bs_ANAHTARINIZ" \
-H "Accept: application/json"
- Anahtar
X-Api-Keybaşlığıyla da gönderilebilir. - Anahtar başına dakikada 120 istek yapılabilir; aşılırsa
429döner. - Anahtarı yalnız sunucunuzda saklayın. Tarayıcı koduna ya da mobil uygulama paketine koymayın.
- Yanıtlar JSON ve UTF-8'dir. Tarihler ISO 8601 biçiminde ve Türkiye saatiyle, tutarlar kuruşsuz tam sayı TL'dir.
Uç noktalar
Aşağıdaki uçlar her anahtara açıktır. Yalnız yayında olan ve satışta gelecek seansı bulunan etkinlikler döner.
| İstek | Ne döner |
|---|---|
| GET /etkinlikler | Etkinlik listesi, sayfa başına 50 kayıt. Öne çıkanlar önce gelir. Yanıtta veri, sayfa, sonSayfa, toplam alanları vardır. |
| GET /etkinlikler/{slug} | Tek etkinlik; açıklama ve kadro da gelir. |
| GET /seanslar/{id} | Tek seans; kategori başına kalan bilet sayısı (kalan) da gelir. |
| GET /mekanlar | Mekânlar, oturma düzeni ve kategori başına koltuk sayısı. |
| GET /rapor | Satışlarınız ve hakedişiniz: haftalık brüt, kesinti, net ve ödeme durumu (ayrıntı: Hakediş raporu). |
| GET / | Anahtarınızın yetkisi ve uç listesi. |
GET /etkinlikler parametreleri
| Parametre | Açıklama | Örnek |
|---|---|---|
| sehir | Seansı bu şehirde olan etkinlikler | İstanbul |
| kategori | Kategori kısa kodu | tiyatro |
| baslangic | Bu tarihte ya da sonrasında seansı olanlar | 2026-11-01 |
| bitis | Bu tarihte ya da öncesinde seansı olanlar | 2026-11-30 |
| sayfa | Sayfa numarası, 1'den başlar | 2 |
Örnek yanıt
GET /etkinlikler yanıtındaki her etkinlik bu yapıdadır. Değerler örnektir.
{
"id": 12,
"slug": "ornek-oyun",
"ad": "Örnek Oyun",
"altBaslik": "",
"kategori": "tiyatro",
"kisaAciklama": "...",
"gorsel": "https://.../afis.jpg",
"kapak": null,
"sure": 90,
"yas": "13+",
"enDusukFiyat": 350,
"url": "https://.../etkinlik/ornek-oyun?ref=bs_AbC1234",
"seanslar": [
{
"id": 45,
"tarih": "2026-11-14T20:30:00+03:00",
"durum": "satista",
"oturma": "numarali",
"mekan": { "slug": "ornek-sahne", "ad": "Örnek Sahne", "sehir": "İstanbul", "ilce": "Kadıköy" },
"fiyatlar": [
{ "kategori": "k1", "ad": "Salon", "fiyat": 450, "ogrenciFiyat": 300 }
],
"url": "https://.../etkinlik/ornek-oyun/45?ref=bs_AbC1234"
}
]
}
oturma:numaraliise seyirci koltuğunu haritadan seçer,numarasizise yalnız adet seçer.fiyatlar[].kategori: salon planındaki kategori; ayakta alangaolarak gelir.ogrenciFiyatboşsa o kategoride öğrenci bileti yoktur.url: ziyaretçiyi göndermeniz gereken bağlantı; satış takibi içinrefparametresi eklenmiş olarak gelir.- Etkinlik detayında ek olarak
aciklamavekadro(ad, rol) alanları bulunur.
Seans ve kalan bilet
GET /seanslar/{id} seans bilgisine ek olarak kategori başına satılabilir bilet sayısını döner. Satılan, o an başka bir ziyaretçinin ayırdığı ve kapatılmış koltuklar düşülmüştür.
{
"veri": {
"id": 45,
"tarih": "2026-11-14T20:30:00+03:00",
"durum": "satista",
"kalan": { "k1": 120, "k2": 34, "ga": 0 },
"...": "..."
}
}
Etkinlik listesini 15 dakikada bir yenilemeniz yeterlidir. Kalan bilet sayısını ise ziyaretçi seansı görüntülediği anda sorgulayın; değer anlıktır.
Satış takibi
Yanıtlardaki bağlantılar ?ref= parametresiyle gelir. Değeri anahtarınızın ilk 10 karakteridir (örneğin bs_AbC1234). Ziyaretçi bu bağlantıyla geldiğinde 30 gün boyunca yaptığı satın almalar platformunuza yazılır.
- Bağlantıları değiştirmeden kullanın,
refparametresini silmeyin. - Kendiniz bağlantı kuruyorsanız herhangi bir etkinlik adresine aynı
?ref=değerini ekleyebilirsiniz. - Ödeme, bilet teslimi ve müşteri desteği Biletsa tarafından yürütülür.
Organizatör sistemleri
Etkinliklerini kendi sisteminde yöneten organizatörler, etkinlik ve seanslarını Biletsa'ya API ile gönderebilir. Bunun için organizatör hesabına bağlı bir anahtar gerekir; organizatör panelindeki kurallar aynen uygulanır.
POST /etkinlikler: etkinlik oluşturur ya da günceller
{
"disId": "sizin-sisteminizdeki-kimlik",
"ad": "Örnek Oyun",
"kategori": "tiyatro",
"sure": 90,
"yas": "13+",
"kisaAciklama": "...",
"aciklama": "...",
"gorsel": "https://.../afis.jpg"
}
- Aynı
disIdya daslugile tekrar gönderilen etkinlik güncellenir. Yeni etkinlik201, güncelleme200döner. - Yeni etkinlikler yönetim onayından sonra yayına girer.
gorselyalnız https adresi olarak kabul edilir.
POST /etkinlikler/{slug}/seanslar: seans ekler ve satışa açar
{
"mekan": "ornek-sahne",
"tarih": "2026-11-14T20:30:00+03:00",
"oturma": "numarali",
"fiyatlar": { "k1": 450, "k2": 350 },
"kapasiteler": { "ga": 200 }
}
mekandeğeriGET /mekanlarlistesindeki slug'dır; kategori anahtarları da oradan gelir.oturma:numaraliya danumarasiz. Numarasız seanstakapasitelerkategori başına satılacak bilet sayısıdır.
Hakediş raporu
GET /rapor satışlarınızı ve hakedişinizi döner. Hesap, organizatör panelindeki Ödemeler sayfasıyla aynıdır: online satılan biletlerin tutarından komisyon, komisyonun KDV'si ve POS payı düşülür, kalan net tutar haftalık ödenir.
- Organizatör anahtarı: kendi etkinliklerinizin online satışları. API ortakları üzerinden satılan biletlerin hakedişi ortağa ödenir; bunlar
satis.ortakalanında bilgi olarak görünür. - Ortak anahtarı (organizatöre bağlı değil): bağlantılarınızdan gelen satışlar sizin satışınızdır. Anlaşmanızdaki komisyon, KDV ve POS düşülerek hakedişiniz size ödenir.
| Parametre | Açıklama | Örnek |
|---|---|---|
| baslangic | İsteğe bağlı. Bu tarihten itibaren olan haftalar ve seanslar | 2026-10-01 |
| bitis | İsteğe bağlı. Bu tarihe kadar (gün dahil) | 2026-10-31 |
Örnek yanıt (organizatör anahtarı)
{
"hesap": { "tur": "organizator", "ad": "Örnek Yapım", "komisyon": 10, "komisyonKdv": 20, "pos": 0, "esas": "seans",
"odemeNotu": "Hakedişler her hafta ödeme gününde ... gönderilir." },
"hakedis": { "brut": 48500, "komisyon": 4850, "kdv": 970, "pos": 0, "kesinti": 5820, "net": 42680,
"odenen": 33440, "bekleyen": 0, "birikiyor": 9240,
"siradakiOdeme": { "tutar": 0, "tarih": "2026-10-28" } },
"satis": {
"online": { "siparis": 41, "bilet": 107, "tutar": 48500 },
"ortak": { "siparis": 3, "bilet": 6, "tutar": 2700 },
"gise": { "siparis": 6, "bilet": 14, "tutar": 6300 }
},
"haftalar": [
{ "hafta": "2026-10-26", "bitis": "2026-11-01", "odemeGunu": "2026-11-04", "durum": "birikiyor",
"bilet": 23, "hediye": 0, "brut": 10500, "komisyon": 1050, "kdv": 210, "pos": 0, "kesinti": 1260, "net": 9240,
"odeme": null, "etkinlikler": [ { "ad": "Örnek Oyun", "brut": 10500, "bilet": 23 } ] },
{ "hafta": "2026-10-19", "bitis": "2026-10-25", "odemeGunu": "2026-10-28", "durum": "odendi",
"bilet": 84, "hediye": 1, "brut": 38000, "komisyon": 3800, "kdv": 760, "pos": 0, "kesinti": 4560, "net": 33440,
"odeme": { "tutar": 33440, "tarih": "2026-10-28", "aciklama": "" }, "etkinlikler": [ "..." ] }
],
"seanslar": [
{ "id": 45, "etkinlik": { "slug": "ornek-oyun", "ad": "Örnek Oyun" }, "tarih": "2026-10-31T20:30:00+03:00",
"durum": "satista", "mekan": { "ad": "Örnek Sahne", "sehir": "İstanbul" },
"online": { "siparis": 9, "bilet": 23, "tutar": 10500 }, "ortak": { "siparis": 1, "bilet": 2, "tutar": 900 },
"gise": { "siparis": 2, "bilet": 5, "tutar": 2250 } }
]
}
Ortak anahtarında yanıt aynı yapıdadır; hesap.tur ortak olur, satis ve seanslar yalnız online (bağlantınızdan gelen satışlar) içerir ve yalnız satış yaptığınız seanslar listelenir.
brut: hakedişe esas online satış tutarı; hizmet bedeli dahil değildir, kupon ve Süper Bilet indirimleri düşülmüştür.kesinti= komisyon + KDV + POS,net= size ödenecek tutar.- Haftalar Pazartesi–Pazar'dır ve her hafta bir sonraki haftanın ödeme gününde (
odemeGunu) ödenir.esasseansise satışlar seansın oynandığı haftaya,satisise satışın yapıldığı haftaya yazılır. durum:birikiyoriçinde bulunulan hafta,bekliyorödemesi yapılacak hafta,odendiödenmiş hafta (odemealanında tutar ve tarih).- Gişe satışının parası organizatörde olduğu için hakedişe girmez; yalnız
gisealanlarında görünür. İptal edilen satışlar rapordan düşer. baslangicvebitisyalnızhaftalar,seanslarvesatisalanlarını süzer;hakedisher zaman tüm zamanları kapsar.- Satış tutarları tam sayı TL'dir; komisyon, KDV, POS, kesinti, net ve ödenen tutarlar kuruşlu olabilir (iki ondalık). Alıcı bilgileri bu uçta yer almaz.
Hatalar
Hatalar uygun HTTP koduyla ve {"hata": "..."} gövdesiyle döner. Mesaj Türkçedir ve kullanıcıya gösterilebilir.
| Kod | Anlamı |
|---|---|
| 401 | Anahtar eksik, geçersiz ya da kapatılmış |
| 403 | Okuma anahtarıyla yazma denendi ya da bağlı organizatör hesabı kapalı |
| 404 | Etkinlik ya da seans bulunamadı |
| 422 | Gönderilen veri geçersiz (ör. bilinmeyen mekân, hatalı tarih) |
| 429 | Dakikalık istek sınırı aşıldı; bir dakika sonra tekrar deneyin |
Geçerli değerler
Filtrelerde kullanabileceğiniz güncel değerler:
Şehirler (sehir)
Kategoriler (kategori)
Anahtar talebi
Platformunuzun adını, web adresinizi ve etkinlikleri nasıl göstereceğinizi yazın. Size okuma anahtarı ya da organizatör anahtarı oluşturalım.
biletsaresmi@gmail.com