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

1

Anahtar alın

Bize yazın, platformunuz için bir API anahtarı oluşturalım. Anahtar yalnız bir kez gösterilir.

2

Etkinlikleri çekin

Satıştaki etkinlikleri, seansları, fiyatları ve kalan bilet sayısını JSON olarak alın.

3

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-Key başlığıyla da gönderilebilir.
  • Anahtar başına dakikada 120 istek yapılabilir; aşılırsa 429 dö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.

İstekNe döner
GET /etkinliklerEtkinlik 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 /mekanlarMekânlar, oturma düzeni ve kategori başına koltuk sayısı.
GET /raporSatış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

ParametreAçıklamaÖrnek
sehirSeansı bu şehirde olan etkinliklerİstanbul
kategoriKategori kısa kodutiyatro
baslangicBu tarihte ya da sonrasında seansı olanlar2026-11-01
bitisBu tarihte ya da öncesinde seansı olanlar2026-11-30
sayfaSayfa numarası, 1'den başlar2

Ö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: numarali ise seyirci koltuğunu haritadan seçer, numarasiz ise yalnız adet seçer.
  • fiyatlar[].kategori: salon planındaki kategori; ayakta alan ga olarak gelir. ogrenciFiyat boşsa o kategoride öğrenci bileti yoktur.
  • url: ziyaretçiyi göndermeniz gereken bağlantı; satış takibi için ref parametresi eklenmiş olarak gelir.
  • Etkinlik detayında ek olarak aciklama ve kadro (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, ref parametresini 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ı disId ya da slug ile tekrar gönderilen etkinlik güncellenir. Yeni etkinlik 201, güncelleme 200 döner.
  • Yeni etkinlikler yönetim onayından sonra yayına girer.
  • gorsel yalnı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 }
}
  • mekan değeri GET /mekanlar listesindeki slug'dır; kategori anahtarları da oradan gelir.
  • oturma: numarali ya da numarasiz. Numarasız seansta kapasiteler kategori 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.ortak alanı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.
ParametreAçıklamaÖrnek
baslangicİsteğe bağlı. Bu tarihten itibaren olan haftalar ve seanslar2026-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. esas seans ise satışlar seansın oynandığı haftaya, satis ise satışın yapıldığı haftaya yazılır.
  • durum: birikiyor içinde bulunulan hafta, bekliyor ödemesi yapılacak hafta, odendi ödenmiş hafta (odeme alanında tutar ve tarih).
  • Gişe satışının parası organizatörde olduğu için hakedişe girmez; yalnız gise alanlarında görünür. İptal edilen satışlar rapordan düşer.
  • baslangic ve bitis yalnız haftalar, seanslar ve satis alanlarını süzer; hakedis her 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.

KodAnlamı
401Anahtar eksik, geçersiz ya da kapatılmış
403Okuma anahtarıyla yazma denendi ya da bağlı organizatör hesabı kapalı
404Etkinlik ya da seans bulunamadı
422Gönderilen veri geçersiz (ör. bilinmeyen mekân, hatalı tarih)
429Dakikalı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)

AdanaAnkaraAntalyaBursaEdirneErzurumEskişehirGaziantepİstanbulİzmirKayseriMalatyaMersinVan

Kategoriler (kategori)

tiyatro · Tiyatroblack-friday · Black Fridaykonser · Konserstandup · Stand-upcocuk · Çocukfutbol · Futbolfestival · Festivalopera · Opera & Baleseminer-workshop · Seminer & Workshop

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