API المنظمين
اجلب فعالياتك وطلباتك وحضورك إلى نظامك الخاص، وتحقق من الدخول ببوابتك الدوارة أو ماسحك الخاص.
العنوان الأساسي: https://tixvio.com/api/v1/ext
المصادقة
يحمل كل طلب مفتاح API في الترويسة Authorization: Bearer txk_…. ينشئ صاحب الحساب المفاتيح من صفحة المطورين في اللوحة؛ يُعرض المفتاح مرة واحدة فقط ولا يحفظ Tixvio سوى بصمته.
ينتمي المفتاح إلى منظم واحد ولا يرى إلا الفعاليات التي يستضيفها. لا تعمل جلسة Tixvio Pro على هذه النقاط، ولا يعمل مفتاح API على نقاط اللوحة أو Pro.
الصلاحية 30 أو 90 أو 365 يومًا أو بلا انتهاء. يمكن أن تكون 10 مفاتيح نشطة كحد أقصى في وقت واحد. ألغِ المفاتيح غير المستخدمة؛ يسري الإلغاء فورًا.
curl https://tixvio.com/api/v1/ext/events?status=upcoming \
-H "Authorization: Bearer txk_…"الصلاحيات
اختر عند الإنشاء الصلاحيات اللازمة فقط. يحصل الطلب إلى نقطة خارج صلاحيات المفتاح على 403 insufficient_scope.
| الصلاحية | المعنى |
|---|---|
events:read | قائمة الفعاليات وتفاصيلها: أنواع التذاكر والسعر والحصة والمباع وأعداد الدخول. |
orders:read | الطلبات المدفوعة والمستردة: اسم المشتري وبريده والمبلغ والخصم والقسيمة والبنود. |
attendees:read | التذاكر ورموز الدخول: الاسم والنوع والحالة ورمز الطلب ووقت الدخول. |
checkin | البوابة: قائمة البوابة دون اتصال (مع مفاتيح QR) ومزامنة الدخول والتحقق من QR عبر الإنترنت. |
الحدود والصفحات
- 120 طلبًا في الدقيقة لكل مفتاح؛ وبعدها يُعاد 429 rate_limited مع Retry-After: 60.
- تأتي القوائم في صفحات من 100 صف: ?page=1، 2، … إذا كانت more في الرد true فهناك صفحة تالية.
- تقبل الطلبات والحضور ?since=<تاريخ ISO> وتعيد ما تغيّر بعد تلك اللحظة فقط (دفع، استرداد، تذكرة جديدة، دخول)؛ احفظ وقت آخر تشغيل عند المزامنة.
- المبالغ أعداد صحيحة بأصغر وحدة (25000 = 250.00) والعملة في الحقل currency. الأوقات بصيغة ISO 8601 (UTC).
نقاط النهاية
كل المسارات تحت العنوان الأساسي. الردود JSON ولا تُخزن مؤقتًا.
| الطريقة | المسار | الصلاحية | المعنى |
|---|---|---|---|
| GET | /me | — | اسم المفتاح وبادئته وصلاحياته وانتهاؤه والمنظم. |
| GET | /events | events:read | الفعاليات. ?status=upcoming (افتراضي) | past | all. |
| GET | /events/{id} | events:read | فعالية واحدة: أنواع التذاكر والمباع والسعة وأعداد الدخول. |
| GET | /events/{id}/orders | orders:read | الطلبات (البيع الأول؛ دون إعادة البيع). ?since و?page. |
| GET | /events/{id}/attendees | attendees:read | التذاكر ورموز الدخول (مباعة ومدعوون وتذاكر مجمعة). ?since و?page. |
| GET | /events/{id}/door | checkin | قائمة البوابة دون اتصال: لكل تذكرة الرمز والحالة والاسم والنوع ونافذة المسح ومفتاح QR. فقط في وقت البوابة (قبل البداية بـ12 ساعة حتى النهاية؛ دون نهاية: البداية + 12 ساعة)، 3 مرات كحد أقصى كل دقيقتين؛ ويُسجَّل كل تنزيل. |
| POST | /events/{id}/checkins | checkin | مزامنة الدخول: { items: [{ code, at, mode }] } (حتى 500). الأسبق يفوز؛ إن أدخل جهاز أو مفتاح آخر التذكرة أولًا يُعاد ALREADY. |
| POST | /scan | checkin | التحقق من QR عبر الإنترنت: { 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" }] }رموز الأخطاء
ردود الخطأ بالشكل { "error": "<الرمز>" }.
| الرمز | HTTP | المعنى |
|---|---|---|
invalid_key | 401 | المفتاح مفقود أو غير معروف أو ملغى أو منتهٍ، أو حساب المنظم غير معتمد. |
insufficient_scope | 403 | المفتاح لا يملك صلاحية هذه النقطة (scope في الرد). |
not_found | 404 | الفعالية غير موجودة أو لا تخص هذا المنظم. |
door_window | 403 | قائمة البوابة متاحة فقط في وقت البوابة (opensAt وclosesAt في الرد). |
invalid_since | 400 | قيمة since ليست تاريخ ISO صالحًا. |
empty | 400 | لا يحتوي الطلب على دخول أو محتوى QR. |
rate_limited | 429 | تجاوزت الحد؛ انتظر عدد ثواني Retry-After. |
التحقق من QR دون اتصال (TX2)
يتغير رمز QR في تذكرة Tixvio كل 30 ثانية، فتفقد لقطة الشاشة صلاحيتها سريعًا. الصيغة: TX2.<رمز التذكرة>.<النافذة>.<التوقيع>.
النافذة = floor(أجزاء الثانية بتوقيت يونكس / 30000). التوقيع = أول 16 حرفًا من نص base64url لـ HMAC-SHA256(المفتاح، رمز التذكرة + "." + النافذة). المفتاح هو حقل key للصف في قائمة البوابة (كنص UTF-8).
بسبب انحراف ساعات الأجهزة تُقبل ±2 نافذة (نحو ±دقيقة). الصف ذو key الفارغ (مستخدم أو مسترد أو معروض لإعادة البيع) لا يُدخل. حقل win هو نافذة المسح [البداية، النهاية]؛ وخارجها تُعد التذكرة OUT_OF_WINDOW.
أرسل حالات الدخول دون اتصال إلى نقطة checkins عند عودة الإنترنت، كي لا يُدخل Tixvio Pro والبوابات الأخرى التذكرة نفسها مرتين.
// 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]
}CSV رموز الدخول
يُنزّل لكل فعالية من صفحة المطورين في اللوحة (المالكون والمديرون). الأعمدة: الرمز والاسم والنوع والحالة والطلب والدخول. UTF-8 (BOM) مع الفاصل ; ليفتحه Excel بشكل صحيح؛ وتُحيَّد الخلايا التي تبدأ برموز الصيغ.
استيراد الباركود الثابت
استيراد باركود ثابت بيع في نظام آخر إلى بوابة Tixvio غير متاح بعد: يمكن مشاركة الرمز الثابت كلقطة شاشة، وهذا يُبطل حماية QR المتغير. إن احتجت إليه فراسلنا عبر الدعم المباشر.