Organizatörler için

Organizatör API’si

Etkinliklerini, siparişlerini ve katılımcılarını kendi sistemine al; kendi turnike ya da tarayıcınla girişi doğrula.

API anahtarı oluştur API ve dışa aktarma rehberi

Temel adres: https://tixvio.com/api/v1/ext

Kimlik doğrulama

Her istek bir API anahtarı taşır: Authorization: Bearer txk_… başlığı. Anahtarı hesabın sahibi panelde Geliştiriciler sayfasından oluşturur; anahtar yalnızca bir kez gösterilir, Tixvio yalnızca özetini saklar.

Anahtar organizatöre bağlıdır ve yalnızca o organizatörün ev sahibi olduğu etkinlikleri görür. Tixvio Pro oturumu bu uçlarda geçmez; API anahtarı da panel ve Pro uçlarında geçmez.

Geçerlilik 30, 90 ya da 365 gün ya da süresiz seçilir. Aynı anda en çok 10 etkin anahtar olabilir. Kullanmadığın anahtarı iptal et; iptal hemen geçerlidir.

curl https://tixvio.com/api/v1/ext/events?status=upcoming \
  -H "Authorization: Bearer txk_…"

İzinler

Anahtar oluştururken yalnızca gereken izinleri seç. İzni olmayan uca gelen istek 403 insufficient_scope alır.

İzin	Anlamı
`events:read`	Etkinlik listesi ve ayrıntısı: bilet tipleri, fiyat, kontenjan, satılan, giriş sayıları.
`orders:read`	Ödenmiş ve iade edilmiş siparişler: alıcı adı ve e-postası, tutar, indirim, kupon, kalemler.
`attendees:read`	Biletler ve giriş kodları: ad, tür, durum, sipariş kodu, giriş saati.
`checkin`	Kapı: çevrimdışı kapı listesi (QR anahtarlarıyla), giriş senkronu ve çevrimiçi QR doğrulama.

Sınırlar ve sayfalama

Anahtar başına dakikada 120 istek; aşılırsa 429 rate_limited ve Retry-After: 60 döner.
Listeler 100’er satırlık sayfalarla gelir: ?page=1, 2, … Yanıttaki more alanı true ise bir sonraki sayfa vardır.
Siparişler ve katılımcılar ?since=<ISO tarih> ile yalnızca o andan sonra değişenleri verir (ödeme, iade, yeni bilet, giriş); eşitlemede son çalışma zamanını sakla.
Tutarlar kuruş cinsinden tam sayıdır (25000 = 250,00); para birimi currency alanındadır. Zamanlar ISO 8601 (UTC).

Uç noktalar

Bütün yollar temel adresin altındadır. Yanıtlar JSON’dur ve önbelleğe alınmaz.

Yöntem	Yol	İzin	Anlamı
GET	`/me`	`—`	Anahtarın adı, öneki, izinleri, bitişi ve organizatör.
GET	`/events`	`events:read`	Etkinlikler. ?status=upcoming (varsayılan) \| past \| all.
GET	`/events/{id}`	`events:read`	Tek etkinlik: bilet tipleri, satılan, kapasite, giriş sayıları.
GET	`/events/{id}/orders`	`orders:read`	Siparişler (birincil satış; ikinci el hariç). ?since, ?page.
GET	`/events/{id}/attendees`	`attendees:read`	Biletler / giriş kodları (satılan, davetli, kombine). ?since, ?page.
GET	`/events/{id}/door`	`checkin`	Çevrimdışı kapı listesi: bilet başına kod, durum, ad, tür, tarama penceresi ve QR anahtarı. Yalnızca kapı zamanında (başlangıçtan 12 saat önce → bitiş; bitiş yoksa başlangıç + 12 saat), 2 dakikada en çok 3 kez; her indirme işlem kaydına yazılır.
POST	`/events/{id}/checkins`	`checkin`	Giriş senkronu: { items: [{ code, at, mode }] } (en çok 500). İlk giren kazanır; başka cihaz ya da anahtar önce içeri aldıysa ALREADY.
POST	`/scan`	`checkin`	Çevrimiçi QR doğrulama: { eventId, payload } → OK, USED, INVALID, EXPIRED, WRONG_EVENT, OUT_OF_WINDOW, REFUNDED, LISTED, CANCELLED.

{
  "events": [{
    "id": "clx…", "slug": "gece-…", "title": "…",
    "status": "PUBLISHED", "startsAt": "2026-11-21T19:00:00.000Z",
    "currency": "TRY", "sold": 412, "capacity": 600,
    "ticketTypes": [{ "id": "clt…", "name": "Genel", "price": 45000, "quantity": 500, "sold": 380 }]
  }],
  "page": 1, "more": false
}

POST https://tixvio.com/api/v1/ext/events/{id}/checkins
{ "items": [{ "code": "K7Q2…", "at": "2026-11-21T22:14:05Z", "mode": "scan" }] }

Hata kodları

Hata yanıtı { "error": "<kod>" } biçimindedir.

Kod	HTTP	Anlamı
`invalid_key`	401	Anahtar yok, tanınmıyor, iptal edilmiş ya da süresi dolmuş; ya da organizatör hesabı onaylı değil.
`insufficient_scope`	403	Anahtarda bu uç noktanın izni yok (yanıtta scope).
`not_found`	404	Etkinlik yok ya da bu organizatörün değil.
`door_window`	403	Kapı listesi yalnızca kapı zamanında verilir (yanıtta opensAt, closesAt).
`invalid_since`	400	since geçerli bir ISO tarih değil.
`empty`	400	Gövdede işlenecek giriş ya da QR yok.
`rate_limited`	429	Hız sınırı aşıldı; Retry-After saniye kadar bekle.

Çevrimdışı QR doğrulama (TX2)

Tixvio biletindeki QR 30 saniyede bir değişir; ekran görüntüsü kısa sürede geçersiz olur. Biçim: TX2.<biletKodu>.<pencere>.<imza>.

pencere = floor(unix milisaniye / 30000). imza = HMAC-SHA256(anahtar, biletKodu + "." + pencere) değerinin base64url metninin ilk 16 karakteri. anahtar, kapı listesindeki satırın key alanıdır (metin olarak, UTF-8).

Cihaz saati kayabileceği için ±2 pencere (yaklaşık ±1 dakika) kabul edilir. key alanı boş olan satır (kullanılmış, iade edilmiş, ikinci elde satışta) içeri alınmaz. Satırın win alanı [başlangıç, bitiş] tarama penceresidir; dışındaysa OUT_OF_WINDOW say.

Çevrimdışı yaptığın girişleri internet gelince checkins ucuna gönder; böylece Tixvio Pro ve diğer kapılar aynı bileti ikinci kez almaz.

// Node.js · list = GET /events/{id}/door
import crypto from 'node:crypto';
const rows = new Map(list.tickets.map((t) => [t.code, t]));

function verify(payload, now = Date.now()) {
  const [ver, code, w, sig] = String(payload).split('.');
  const row = rows.get(code);
  if (ver !== 'TX2' || !row || !row.key) return false;
  const win = Math.floor(now / 30000);
  if (Math.abs(Number(w) - win) > 2) return false; // EXPIRED
  const expected = crypto.createHmac('sha256', row.key)
    .update(`${code}.${w}`).digest('base64url').slice(0, 16);
  return expected === sig; // + row.win [from, to]
}

Giriş kodu CSV’si

Panelde Geliştiriciler sayfasından etkinlik başına indirilir (sahip ve yönetici). Sütunlar: kod, ad soyad, tür, durum, sipariş, giriş. UTF-8 (BOM) ve ; ayırıcıyla Excel’de doğru açılır; formül karakterleriyle başlayan hücreler etkisizleştirilir.

Sabit barkod içe aktarma

Başka bir sistemde satılmış sabit barkodları Tixvio kapısına aktarmak şimdilik yok: sabit kod ekran görüntüsüyle paylaşılabildiği için dinamik QR korumasını boşa çıkarır. İhtiyacın varsa canlı destekten bize yaz.