التذاكر والبطاقات والرسائل

ما التذكرة

التذكرة دخول واحد: مقعد واحد في فعالية بمقاعد محجوزة، أو مكان واحد في فعالية دخول عام. رقمها المرجعي رقم الطلب مع رقم (TKT-1042-1)، وتحمل المقعد واسم الحامل من الطلب ونوع التذكرة وما دُفع لأجلها.

البطاقات وتذاكر PDF وملفات التقويم

• يعرض تأكيد الطلب وصفحة تذاكري للحاضر بطاقة لكل تذكرة، برمز QR والمقعد والحامل ونوع التذكرة، بالإنجليزية أو العربية.
• نزّل التذاكر يفتح ملف PDF فيه كل تذكرة صالحة في الطلب، واحدة في كل صفحة A4، مرسومة بلون الفعالية مع رمز QR؛ وتنزّل البطاقة المفردة ملف PDF الخاص بها. نص ملف PDF لاتيني فقط، لذلك فالنسخة العربية من التذكرة هي بطاقة الويب.
• أضف إلى التقويم ينزّل ملف تقويم للفعالية، فيه المكان ورابط صفحة الفعالية.
• روابط التنزيل موقَّعة وتعمل 30 دقيقة؛ وتصنع الصفحة روابط جديدة في كل مرة تُفتح. وتُبنى من PUBLIC_API_URL في واجهة API، فاضبطه على العنوان العام لواجهة API.

رموز QR

• يحمل رمز QR كودًا يبدأ بـ TKY.، وهو توقيع للرقم المرجعي للتذكرة صُنع بـ TICKET_SECRET (أو JWT_SECRET في واجهة API عند عدم ضبطه). ولا يحتوي أي شيء شخصي.
• لا يُخزَّن إلا بصمة كل رمز، فلا تحتفظ قاعدة البيانات بتذكرة قابلة للاستخدام أبدًا.
• اضبط `TICKET_SECRET` مرة واحدة، قبل أن تبيع. تغييره لاحقًا يجعل كل رمز QR صدر يتوقف عن العمل عند الباب.

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

الرسائل

• اضبط RESEND_API_KEY وMAIL_FROM (مثل Ticketory <tickets@your-domain.com>) في .env الخاص بواجهة API لإرسالها عبر Resend. والرد على رسالة تذكرة يذهب إلى بريد دعم مساحة العمل. كل بريد عن طلب (التذاكر والاستردادات وإشعار الإلغاء والتذكير) يُكتب باللغة التي قُدّم بها الطلب، الإنجليزية أو العربية، مع عنوان الفعالية بتلك اللغة؛ وإعادة الإرسال المطلوبة من الموقع تتبع لغة الصفحة. ورسائل التحقق وإعادة الضبط تتبع الصفحة التي استخدمها الحاضر.
• من دونهما يُكتب كل بريد في سجل واجهة API بدلًا من إرساله، وهناك يُقرأ رمز التحقق في تثبيت جديد (مع Docker: docker compose logs api). وتقول صفحة التأكيد حينئذ إن التذاكر جاهزة للتنزيل.
• يُعاد الإرسال الفاشل حتى ست مرات، بانتظار يطول. وتعرض صفحة التأكيد حالة البريد وتتيح أعد إرسال الرسالة، مرة كل دقيقة.
• مفاتيح الإشعارات في اللوحة تغيّر ما يُخبَر به الفريق؛ ولا توقف أبدًا وصول بريد إلى مشترٍ.

تذكيرات الفعاليات

• الحاضر الذي له حساب ويُبقي تذكيرات الفعاليات مفعّلة في ملفه الشخصي (مفعّلة افتراضيًا) يصله بريد واحد لكل فعالية، قبل نحو 24 ساعة من أول جلسة لديه تذاكر صالحة لها، يسرد تلك التذاكر مع مقاعدها ورابطًا إلى تذاكري.
• تبحث واجهة API عن التذكيرات المستحقة بعد دقيقة من بدئها ثم كل 15 دقيقة. يُسجَّل كل تذكير في الجدول event_reminders قبل إرساله، فلا يخرج أي منها مرتين، حتى بعد إعادة التشغيل أو مع نسختين من واجهة API. والإرسال الفاشل يُعاد حتى ثلاث مرات ما دامت الفعالية في المستقبل.
• التذاكر المستردّة والمعلّقة والملغاة، والطلبات غير المدفوعة، والفعاليات الملغاة أو المسودة، لا تحصل على شيء منها، وكذلك الطلب المدفوع بعد وقت التذكير، لأن تذاكره أُرسلت للتو.
• يغيّر EVENT_REMINDER_HOURS في .env الخاص بواجهة API المدة المسبقة (أقصاها 168، أسبوع)، و0 يوقف التذكيرات. ومن دون مزوّد بريد يُكتب كل تذكير في سجل واجهة API، مثل كل بريد آخر.
• مفتاح الأخبار والعروض في الملف الشخصي يُحفظ كاختيار للحاضر فقط: لا يرسل القالب رسائل أخبار أو عروض.

• إعدادات البريد الإلكتروني

إعادة الإصدار والإلغاء

• إعادة إصدار على تذكرة في صفحة الطلب تعطيها رمز QR جديدًا: يتوقف القديم عن العمل عند الباب فورًا، وتُرسل التذاكر بالبريد مرة أخرى بالرمز الجديد. لا تُعاد إلا تذكرة صالحة.
• إلغاء لتذكرة لم يدفع أحد ثمنها، كالمجانية. يعود مقعدها أو مكانها للبيع فورًا، إلا إذا كان حاملها قد دخل بالفعل. أما التذكرة المدفوعة فتُسترد بدلًا من ذلك، وهذا يُبقي المال وحق الدخول متوافقين.
• كلاهما يحتاج إلى tickets.manage الذي يملكه دورا المالك والمالية التجريبيان، وكلاهما يُكتب في الجدول الزمني للطلب.

• الطلبات والمدفوعات والاستردادات

المسارات خلفها

• يجيب GET /api/orders/:reference/receipt بالطلب وتذاكره مع صورة QR ما دام الطلب مدفوعًا، وحالة البريد، وdownloads الموقّعة. ويحتاج إلى رمز وصول الطلب أو رمز الحاضر.
• تأخذ GET /api/orders/:reference/tickets.pdf وGET /api/orders/:reference/calendar.ics وGET /api/tickets/:reference/pdf رابطًا موقّعًا (?exp=&sig=)؛ والخاطئ أو المنتهي هو 404.
• يضع POST /api/orders/:reference/resend-email البريد في قائمة الإرسال مرة أخرى؛ وقبل مرور دقيقة هو 429 COOLDOWN.
• يحتاج POST /api/admin/tickets/:reference/reissue و/void إلى tickets.manage. وإلغاء تذكرة مدفوعة هو 409 USE_REFUND.

• مرجع واجهة API