مرجع واجهة API

كل مسار تقدّمه واجهة API، ومن يستطيع استدعاءه، وكيف تعمل مسارات تسجيل الدخول والصلاحيات ومساحات العمل والحجوزات والمدفوعات والأخطاء والقوائم والحدود.

لحزمة الحزمة الكاملة

العنوان الأساسي وصيغة الاستجابة

كل مسار يُقدَّم تحت البادئة /api. محليًا يكون العنوان الأساسي http://localhost:8000/api. وعلى الخادم يكون عنوان واجهة API متبوعًا بـ /api، وهو القيمة نفسها التي يقرؤها التطبيقان الأماميان من NEXT_PUBLIC_API_BASE_URL (متغيرات البيئة). وتُقدَّم الصور خارج البادئة، على /media/….

مسارات الموقع عامة أو تأخذ رمز الحاضر؛ ومسارات اللوحة تحتاج إلى رمز bearer لموظف، ومعظمها إلى صلاحية أيضًا. أجسام الطلبات JSON، عدا رفع الملفات. وكل إجابة تأتي في الغلاف نفسه:

الغلاف

{
  "success": true,
  "data": { },
  "message": ""
}

يحمل data النتيجة. وmessage جملة قصيرة تملؤها بعض عمليات الكتابة، بلغة الطلب، وتكون فارغة في غير ذلك. المال عدد صحيح بأصغر وحدة مع currency الخاصة به (price_minor: 2000 تعني 20.00)، وكل تاريخ نص ISO بتوقيت UTC؛ وتحمل كل فعالية أيضًا time_zone الخاص بها.

فحص السلامة لا يحتاج إلى رمز:

الطرفية

curl http://localhost:8000/api/health

الاستجابة

{"success":true,"data":{"status":"ok","database":"up"},"message":""}

عندما يتعذر قراءة قاعدة البيانات يجيب أيضًا بـ 200، مع "status":"degraded" و"database":"down". يقرأ فحص السلامة في صورة Docker هذا الحقل.

الأخطاء

يحتفظ الفشل بالغلاف، مع success: false وحالة HTTP:

الخطأ

{
  "success": false,
  "data": null,
  "message": "…",
  "errors": { "email": ["…"] },
  "code": "SEAT_UNAVAILABLE",
  "details": { "seats": ["A12"] }
}

message جملة بلغة الطلب.
يظهر errors عند فشل التحقق، مع المشكلات لكل حقل، مفهرسة بالمسار الذي أرسله العميل (مثل title.en أو attendee.email).
الحقل المجهول في الجسم يُرفض بـ 400، ويسمّيه errors. والتسجيل، مثلًا، لا يأخذ إلا الحقول المسرودة أدناه.
يظهر code وdetails حيث تتفاعل شاشة مع رفض بعينه: SEAT_UNAVAILABLE مع المقاعد المأخوذة، وHOLD_EXPIRED وSOLD_OUT وALREADY_ADMITTED مع أول إدخال، وVERSION_CONFLICT وNOT_READY مع ما ينقص، وCOOLDOWN مع retry_after بالثواني.
المسار المحمي من دون رمز، أو برمز منتهي، يجيب بـ 401؛ والرمز الذي ينقصه الصلاحية يجيب بـ 403.
الطلب الذي يتجاوز حدًّا يُجاب بـ 429.

الترويسات

الترويسة	تُرسل مع	ما تحمله
`Authorization: Bearer …`	مسارات الموظفين والحضور	الرمز من `POST /api/auth/login` (الموظفون) أو `POST /api/customer-auth/login` (الحضور). النوعان غير قابلين للتبادل
`X-Workspace-Id`	مسارات الموظفين	مساحة العمل التي يخصها الطلب. ما لا ينتمي إليه العضو يُتجاهل وتُستخدم مساحته
`X-Hold-Token`	حجز والدفع المبني عليه	سر الحجز، يُعاد مرة واحدة عند إنشاء الحجز
`X-Order-Token`	مسارات طلب الضيف	سر الطلب، يعيده `POST /api/checkout` مرة واحدة. وطلبات الحاضر المسجَّل دخوله تحتاج إلى رمزه فقط
`Idempotency-Key`	`POST /api/holds`, `POST /api/checkout`, `POST /api/admin/orders/:reference/refunds`	UUID يُصنع عند فتح النموذج. إعادة المحاولة بالمفتاح والجسم نفسهما تعيد الإجابة الأولى بدلًا من تكرار العمل؛ ومن دونه يُرفض الطلب
`Accept-Language`	أي مسار	`ar` لرسائل بالعربية؛ وأي قيمة أخرى تجيب بالإنجليزية

نصوص الفعاليات والأماكن وأنواع التذاكر تحمل اللغتين بالشكل { "en": "…", "ar": "…" } أيًّا كانت قيمة Accept-Language، ويختار العميل إحداهما، ويرجع إلى الإنجليزية حين تكون العربية فارغة.

القوائم والتقسيم إلى صفحات

قائمة

{ "data": [ ], "page": 1, "limit": 10, "total": 36, "totalPages": 4 }

معظم القوائم تُقسَّم إلى صفحات بـ page وlimit، بحد أقصى 100 في الصفحة: 9 فعاليات في الصفحة في الموقع، و10 فعاليات وأماكن وحضور و8 طلبات في اللوحة افتراضيًا. وبعضها يعيد أيضًا counts لكل تبويب أو حالة.
قوائم الفريق والأدوار وإعدادات الموقع تُقسَّم بـ page وpage_count، والاستفسارات بـ page وpage_size (10 افتراضيًا، 50 على الأكثر).
قوائم اللوحة تأتي الأحدث تحديثًا أولًا، مع المعرّف كفاصل عند التساوي، فيكون التصفح بين الصفحات ثابتًا. وكتالوج الموقع يأتي الأقرب أولًا.
فلاتر قائمة الفريق (email وname وphone) تجتمع: يجب أن يطابق الصف كل فلتر معطى. ويطابق name الاسم الأول واسم العائلة واسم المستخدم والاسم الكامل.

01
سجّل الدخول كموظف
الطرفية
```
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"YOUR_EMAIL","password":"YOUR_PASSWORD"}'
```
استخدم أحد حسابات اللوحة من التثبيت، أو حسابك. data.access_token هو الرمز، مع token_type بالقيمة Bearer والموظف بأدواره وصلاحياته. يدوم الرمز JWT_EXPIRATION، وهو 7d افتراضيًا، ويعيد expires_in تلك القيمة كما كُتبت. ويعيد GET /api/auth/me الموظف المسجَّل دخوله بأدواره وصلاحياته.

استدعِ مسارًا محميًا

الطرفية

curl http://localhost:8000/api/admin/orders \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Workspace-Id: 1"

البريد غير المعروف وكلمة المرور الخاطئة يجيبان كلاهما بـ 401 مع الرسالة نفسها.
عشر محاولات دخول فاشلة من عنوان واحد خلال 15 دقيقة تجيب 429 إلى أن يمضي على أقدم فشل 15 دقيقة (RATE_LIMIT_LOGIN). ولا تُحسب عمليات الدخول الناجحة. ويُحسب دخول الموظفين ودخول الحضور كلٌّ على حدة.
حسابات الموظفين تأتي من البيانات التجريبية أو من صفحة الفريق؛ ولا يوجد تسجيل للموظفين. ويسجّل العميل الخروج بنسيان رمزه.
يسرد GET /api/admin/workspace/memberships مساحات العمل التي ينتمي إليها العضو، وأولها مساحته. أرسل معرّف المساحة المختارة باسم X-Workspace-Id.

الطريقة	المسار	من يحق له استدعاؤه	وظيفته
`POST`	`/api/auth/login`	أي شخص	دخول الموظف: `email` و`password`
`GET`	`/api/auth/me`	أي موظف مسجَّل الدخول	الموظف المسجَّل دخوله، وأدواره وصلاحياته
`GET`	`/api/admin/workspace/memberships`	أي موظف مسجَّل الدخول	مساحات عمل العضو، لمنتقي الشريط العلوي

الصلاحيات

تفحص مسارات الموظفين صلاحية اسمها <area>.<action>. يملك العضو كل صلاحية من كل دور لديه، والدور نفسه في كل مساحة عمل ينتمي إليها. الصلاحيات التسع والعشرون والأدوار الأربعة التجريبية (المالك والمدير والمالية وتسجيل الدخول) مسرودة في الفريق والأدوار ومساحات العمل.

الفعاليات والأماكن والمنظّمون على الموقع

الطريقة	المسار	من يحق له استدعاؤه	وظيفته
`GET`	`/api/public/events`	أي شخص	الفعاليات العامة القادمة، الأقرب أولًا. `q` (العنوان أو الملخص أو المكان أو المدينة أو المنظّم)، و`category`، و`city`، و`venue`، و`organiser` (معرّفات نصية)، و`from` و`to` (`YYYY-MM-DD`)، و`page`، و`limit`. وتُستبعد المسودات والفعاليات غير المدرجة والفعاليات التي انتهت
`GET`	`/api/public/events/cities`	أي شخص	المدن التي فيها فعاليات قادمة وعدد فعاليات كل منها، لفلتر المدينة
`GET`	`/api/public/events/:slug`	أي شخص	فعالية كاملة: الوصف والبرنامج والمكان بعنوانه وإمكانية الوصول والمواصلات والموقع، ورمز الجلسة، وأنواع التذاكر بسعرها ورسومها والأماكن المتبقية وحد الطلب الواحد. والفعالية الملغاة تجيب بـ `status: cancelled`
`GET`	`/api/public/sessions/:code/availability`	أي شخص	التوفر الحي لخريطة المقاعد: ساعة الخادم، و`hold_seconds`، و`max_per_order`، والرسوم، وأنواع التذاكر، ومخطط المقاعد المنشور (أو `null` للدخول العام)، وكل مقعد بحالة `available` أو `held` أو `sold` أو `unavailable`
`GET`	`/api/public/categories`	أي شخص	فئات الفعاليات
`GET`	`/api/public/organisers`	أي شخص	المنظّمون
`GET`	`/api/public/organisers/:slug`	أي شخص	منظّم واحد مع ما يصل إلى 24 من فعالياته القادمة وإجمالي عددها
`GET`	`/api/public/venues`	أي شخص	الأماكن، مع فعالياتها القادمة ومقاعدها
`GET`	`/api/public/venues/:slug`	أي شخص	مكان واحد، مع مخطط مقاعده المنشور
`GET`	`/api/public/settings`	أي شخص	ما يحتاجه الموقع لتسعير عملية الشراء وتوقيتها: اسم مساحة العمل، و`currency`، و`fee_bps` (رسوم الحجز التي يدفعها الحاضر على كل تذكرة، و`300` تعني 3%)، و`hold_seconds`، و`max_per_order`، و`time_zone`، و`support_email`، و`payment_methods`، و`mail_simulated` (صحيح ما دامت الرسائل تُكتب في سجل واجهة API)
`GET`	`/api/settings/public`	أي شخص	قيم الموقع `site_name` و`contact_email` و`contact_city`

أرباح المنظّم ليست جزءًا من أي إجابة عامة أبدًا.

حسابات الحضور

الطريقة	المسار	من يحق له استدعاؤه	وظيفته
`POST`	`/api/customer-auth/register`	أي شخص	التسجيل: `first_name` و`last_name` و`email` و`password` (من 8 إلى 72 حرفًا فيها حرف ورقم) و`terms_accepted` (`true`)، واختياريًا `role` (`attendee` أو `organiser`، ولا يُقرأ أبدًا). وأي حقل آخر يجيب `400` ويسمّيه. يجيب `201`، مع تسجيل الدخول فورًا، ويرسل رمزًا من ستة أرقام
`POST`	`/api/customer-auth/login`	أي شخص	دخول الحاضر: `email` و`password`، و`remember` لرمز مدته 30 يومًا بدلًا من يوم واحد
`POST`	`/api/customer-auth/logout`	أي شخص	يجيب `{ signed_out: true }`؛ الرموز بلا حالة، فينسى العميل نسخته
`POST`	`/api/customer-auth/forgot-password`	أي شخص	`email`. يرسل رابط إعادة ضبط صالحًا ساعة واحدة إذا كان الحساب موجودًا، ويجيب بالطريقة نفسها في الحالتين
`POST`	`/api/customer-auth/reset-password`	أي شخص	`token` (من الرابط) و`password` الجديد. والرابط المنتهي أو المستخدم يجيب `400` مع `TOKEN_EXPIRED`
`POST`	`/api/customer-auth/verify-email`	حاضر مسجَّل الدخول	`code`، الأرقام الستة من البريد، صالح 24 ساعة. والطلبات التي اشتُريت بذلك البريد كضيف تنضم إلى الحساب
`POST`	`/api/customer-auth/resend-verification`	حاضر مسجَّل الدخول	أرسل رمزًا جديدًا؛ مرة واحدة في الدقيقة على الأكثر (`429` مع `COOLDOWN` و`retry_after`)
`GET`	`/api/me`	حاضر مسجَّل الدخول	الملف الشخصي للحاضر
`PATCH`	`/api/me`	حاضر مسجَّل الدخول	غيّر `first_name` أو `last_name` أو `email` أو `marketing_emails` أو `reminder_emails`
`GET`	`/api/me/saved`	حاضر مسجَّل الدخول	الفعاليات المحفوظة، كبطاقات
`GET`	`/api/me/saved/slugs`	حاضر مسجَّل الدخول	معرّفات الفعاليات المحفوظة فقط، لأزرار القلب
`PUT`	`/api/me/saved/:slug`	حاضر مسجَّل الدخول	احفظ فعالية
`DELETE`	`/api/me/saved/:slug`	حاضر مسجَّل الدخول	ألغِ حفظ فعالية
`GET`	`/api/me/tickets`	حاضر مسجَّل الدخول	تذاكر الحاضر كـ `upcoming` و`past`، بطاقة لكل طلب
`GET`	`/api/me/tickets/:reference`	حاضر مسجَّل الدخول	بطاقات طلب واحد، مع رموز QR وروابط التنزيل
`GET`	`/api/me/orders`	حاضر مسجَّل الدخول	طلبات الحاضر
`GET`	`/api/me/orders/:reference`	حاضر مسجَّل الدخول	إيصال طلب واحد، مع جدوله الزمني

التسجيل محدود بـ 10 لكل عنوان في 10 دقائق، وطلبات إعادة ضبط كلمة المرور بـ 5. وما دام مفتاح البريد غير مضبوط، تُكتب الرموز والروابط في سجل واجهة API، ويقول mail_simulated ذلك.

الحجوزات والدفع

الشراء استدعاءان: احجز المقاعد أو الأماكن، ثم أتمّ الدفع من الحجز. كلاهما يعمل للضيف وللحاضر المسجَّل دخوله، الذي يُقرأ رمزه حين يُرسل.

الطريقة	المسار	من يحق له استدعاؤه	وظيفته
`POST`	`/api/holds`	أي شخص	احجز `{ session_code, seats: ["A12", "B12"] }` للمقاعد المحجوزة، أو `{ session_code, ticket_type_id, quantity }` للدخول العام، من 1 إلى 8 في المرة. يحتاج إلى `Idempotency-Key`. يجيب `201` مع الحجز و`expires_at` وساعة الخادم، و`token` الخاص به، ويظهر مرة واحدة
`GET`	`/api/holds/:id`	مالك الحجز، مع `X-Hold-Token`	اقرأ الحجز
`PATCH`	`/api/holds/:id`	مالك الحجز، مع `X-Hold-Token`	استبدل الاختيار؛ لا يتحرك الموعد النهائي
`DELETE`	`/api/holds/:id`	مالك الحجز، مع `X-Hold-Token`	حرّر المقاعد الآن
`GET`	`/api/checkout/methods`	أي شخص	طرق الدفع المعروضة، لكل منها `provider` و`live`
`POST`	`/api/checkout`	مالك الحجز، مع `X-Hold-Token`	`hold_id` و`attendee` (`first_name` و`last_name` و`email`) و`provider` (`stripe` أو `paypal` أو `simulated`) و`terms_accepted`. يحتاج إلى `Idempotency-Key`. يجيب `201` مع `order_reference` و`status` و`redirect_url` و`access_token`، وهو سر الطلب ويظهر مرة واحدة. ويُحفظ `Accept-Language` الخاص بالطلب (`ar`، وإلا `en`) على الطلب باسم `locale`، وهو لغة كل بريد عنه

يدوم الحجز مدة حجز مساحة العمل (hold_seconds، عشر دقائق في البيانات التجريبية)، محسوبة بساعة الخادم. وبعدها يجيب الحجز 410 مع HOLD_EXPIRED وتصبح المقاعد متاحة من جديد.
المقعد الذي يحجزه شخص آخر أو اشتراه يجيب 409 مع SEAT_UNAVAILABLE والمقاعد في details.seats؛ ونوع التذكرة الممتلئ يجيب SOLD_OUT؛ وما يزيد على حد الطلب الواحد يجيب TOO_MANY.
وجّه المتصفح إلى redirect_url: صفحة Stripe أو PayPal نفسها، أو صفحة المحاكي في الموقع. ولا تُرسل بيانات البطاقة إلى واجهة API هذه أبدًا.
الحجز الذي إجماليه 0 لا يحتاج إلى provider: يُؤكَّد الطلب فورًا بالمزوّد free والحالة paid، وredirect_url هو صفحة تأكيده.

الطلبات وملفات التذاكر والمدفوعات

الطريقة	المسار	من يحق له استدعاؤه	وظيفته
`GET`	`/api/orders/:reference/status`	حاضر الطلب، أو ضيف مع `X-Order-Token`	`status` (`pending_payment` أو `paid` أو `payment_failed` أو `expired` أو `payment_review` أو `partially_refunded` أو `refunded`)، والمزوّد وساعة الخادم، للصفحة التي تنتظر الدفع
`GET`	`/api/orders/:reference/receipt`	حاضر الطلب، أو ضيف مع `X-Order-Token`	الطلب مع فعاليته ومكانه وتذاكره (كل تذكرة مدفوعة برمز QR الخاص بها) وحالة بريد التذاكر وروابط `downloads` الموقّعة
`POST`	`/api/orders/:reference/resend-email`	حاضر الطلب، أو ضيف مع `X-Order-Token`	أرسل التذاكر مرة أخرى إلى عنوان الطلب، بلغة `Accept-Language` الخاص بالطلب. يجيب `202`، أو `429` مع `COOLDOWN` خلال دقيقة من آخر إرسال
`GET`	`/api/orders/:reference/tickets.pdf`	أي شخص يحمل الرابط الموقّع	كل تذاكر الطلب في ملف PDF واحد
`GET`	`/api/orders/:reference/calendar.ics`	أي شخص يحمل الرابط الموقّع	الفعالية كملف تقويم
`GET`	`/api/tickets/:reference/pdf`	أي شخص يحمل الرابط الموقّع	تذكرة واحدة كملف PDF
`GET`	`/api/payments/return/paypal`	أي شخص	يرسل PayPal المشتري إلى هنا: تلتقط واجهة API الدفعة وتعيد التوجيه إلى صفحة انتظار الموقع (أو صفحة الإلغاء)
`POST`	`/api/payments/simulated/:reference/complete`	صفحة المحاكي، مع رمز الطلب	`token` و`outcome` (`pay` أو `fail` أو `cancel`). يجيب `404` متى لم يكن المحاكي معروضًا
`POST`	`/api/webhooks/:provider`	Stripe أو PayPal	`stripe` أو `paypal`. يُفحص التوقيع مقابل `STRIPE_WEBHOOK_SECRET` أو `PAYPAL_WEBHOOK_ID`؛ والمفقود أو الخاطئ يجيب `401`. ويُعالَج كل حدث مرة واحدة مهما تكرر إرساله

روابط التنزيل موقّعة بـ exp وsig وتعمل 30 دقيقة من الإيصال الذي صنعها؛ والقديم يجيب 404، وقراءة الإيصال من جديد تصنع روابط جديدة. وتُبنى من PUBLIC_API_URL.
تُصدر التذاكر متى أكد المزوّد الدفعة، بخطاف الويب الخاص به، أو بعودة PayPal، أو بالمحاكي. يرسل Stripe checkout.session.completed وcheckout.session.async_payment_succeeded وcheckout.session.async_payment_failed وrefund.updated؛ ويرسل PayPal PAYMENT.CAPTURE.COMPLETED وPAYMENT.CAPTURE.DENIED وPAYMENT.CAPTURE.REFUNDED.
يُعرض المحاكي ما دام لا يوجد مفتاح Stripe أو PayPal حي؛ وPAYMENTS_SIMULATOR=on أو off يتقدم على ذلك.

الإطلاق

نموذج التواصل

الطريقة	المسار	من يحق له استدعاؤه	وظيفته
`POST`	`/api/leads`	أي شخص	`name` و`email` و`subject` (`general` أو `tickets` أو `organisers` أو `scale` أو `press`) و`message` (من 10 إلى 2000 حرف) و`client_token` (UUID v4). يجيب `201` مع `{ id, received_at }`

يعيد client_token المكرر إيصال الإرسال الأول بدل تخزين إرسال ثانٍ.
يُعامل الحقل company المملوء كأنه روبوت: يبدو الرد نفسه، ولا يُخزَّن شيء.
يستطيع كل عنوان إرسال خمس في عشر دقائق؛ والتالية تجيب 429.

الفعاليات

الطريقة	المسار	من يحق له استدعاؤه	وظيفته
`GET`	`/api/admin/events`	الموظفون الذين لديهم `events.view`	الفعاليات مع `counts` لكل تبويب. `tab` (`all` أو `published` أو `draft` أو `ended`)، و`q`، و`category`، و`status`، و`venue` (المعرّف)، و`from`، و`to`، و`sort` (`starts_at`، وإلا آخر تحديث)، و`order` (`asc` أو `desc`)، و`page`، و`limit`
`GET`	`/api/admin/events/:id`	الموظفون الذين لديهم `events.view`	فعالية واحدة للمحرر، مع قائمة `readiness` و`version` والبداية والنهاية بالتوقيت المحلي
`POST`	`/api/admin/events`	الموظفون الذين لديهم `events.edit`	أنشئ مسودة: `title` و`summary` و`description` (لكل منها `en` و`ar`)، و`category` (معرّف نصي)، و`venue_id`، و`color` (`pink` أو `yellow` أو `teal` أو `blue`)، و`admission_mode` (`reserved` أو `general`)، و`visibility` (`public` أو `unlisted`)، و`starts_local` و`ends_local` و`time_zone` و`agenda` و`ticket_types` (`title` و`price_minor` و`capacity`، واختياريًا `description` و`max_per_order` و`status`)، واختياريًا `slug`
`PATCH`	`/api/admin/events/:id`	الموظفون الذين لديهم `events.edit`	احفظ الحقول نفسها مع `version` الذي حمّله المحرر. حفظ أحدث يجيب `409` مع `VERSION_CONFLICT`؛ وسعر نوع التذكرة المباع مقفل (`PRICE_LOCKED`)
`POST`	`/api/admin/events/:id/publish`	الموظفون الذين لديهم `events.publish`	اعرض مسودة للبيع. التي ليست جاهزة تجيب `400` مع `NOT_READY` وما ينقص
`POST`	`/api/admin/events/:id/unpublish`	الموظفون الذين لديهم `events.publish`	العودة إلى مسودة: يتوقف البيع وتُحرَّر الحجوزات، وتبقى التذاكر المباعة صالحة
`POST`	`/api/admin/events/:id/cancel`	الموظفون الذين لديهم `events.publish`	`{ confirm }`، المعرّف النصي للفعالية مكتوبًا بالكامل. يتوقف البيع والدخول، ويصل بريد إلى صاحب كل طلب مدفوع. ثم تُجرى الاستردادات لكل طلب
`POST`	`/api/admin/events/:id/duplicate`	الموظفون الذين لديهم `events.edit`	مسودة جديدة بالتفاصيل وأنواع التذاكر نفسها، وبلا مبيعات
`POST`	`/api/admin/events/:id/archive`	الموظفون الذين لديهم `events.publish`	أرشف مسودة، أو فعالية انتهت أو أُلغيت
`GET`	`/api/admin/events/:id/attendees`	الموظفون الذين لديهم `events.view`	تذاكر الفعالية مع الحامل والمقعد والنوع والحالة ووقت الدخول. `q` و`status` (`admitted` أو `not_admitted` أو `void`) و`page` و`limit`

الأماكن ومخططات المقاعد

الطريقة	المسار	من يحق له استدعاؤه	وظيفته
`GET`	`/api/admin/venues`	الموظفون الذين لديهم `venues.view`	الأماكن. `q` و`city` و`page` و`limit`
`GET`	`/api/admin/venues/map`	الموظفون الذين لديهم `venues.view`	دبوس كل مكان للخريطة
`GET`	`/api/admin/venues/:id`	الموظفون الذين لديهم `venues.view`	مكان واحد مع مخططاته
`POST`	`/api/admin/venues`	الموظفون الذين لديهم `venues.edit`	أضف مكانًا: `name` (`en` و`ar`)، و`address`، و`city`، و`time_zone`، و`capacity`، و`accessibility` (`en` و`ar`)، واختياريًا `slug` و`transit` و`location` (`latitude` و`longitude`)
`PATCH`	`/api/admin/venues/:id`	الموظفون الذين لديهم `venues.edit`	غيّر أيًّا من هذه الحقول
`GET`	`/api/admin/venues/:id/layouts`	الموظفون الذين لديهم `venues.view`	إصدارات مخطط المكان
`GET`	`/api/admin/venues/:id/layouts/:version`	الموظفون الذين لديهم `venues.view`	إصدار واحد مع مقاعده
`POST`	`/api/admin/venues/:id/layouts`	الموظفون الذين لديهم `venues.edit`	ابدأ مسودة جديدة
`PATCH`	`/api/admin/venues/:id/layouts/:version`	الموظفون الذين لديهم `venues.edit`	احفظ المسودة: `rows` (من 1 إلى 40)، و`seats_per_row` (من 1 إلى 60)، و`aisles_after` (حتى 6)، و`seats` (`label`، واختياريًا `accessible` و`companion` و`disabled` و`price_tier` من 0 إلى 9) و`loaded_at`. المسودة التي حفظها شخص آخر منذ ذلك تجيب `409` مع `VERSION_CONFLICT`
`POST`	`/api/admin/venues/:id/layouts/:version/publish`	الموظفون الذين لديهم `venues.edit`	`{ acknowledged: true }`. ينشر المسودة كمخطط للمكان؛ وتحتفظ المقاعد المباعة بالإصدار الذي بيعت عليه. ويُرفض المخطط الفارغ، أو الذي فيه مقاعد أكثر من سعة المكان (`OVER_CAPACITY`)

الطلبات والتذاكر والاستردادات

الطريقة	المسار	من يحق له استدعاؤه	وظيفته
`GET`	`/api/admin/orders`	الموظفون الذين لديهم `orders.view`	الطلبات مع `counts` لكل حالة. `status` (`paid` أو `pending_payment` أو `refunded` أو `payment_failed` أو `payment_review`)، و`event` (معرّف نصي)، و`provider` (`stripe` أو `paypal` أو `simulated` أو `free`)، و`q` (الرقم المرجعي أو البريد أو الاسم)، و`from` و`to` و`page` و`limit`
`GET`	`/api/admin/orders/events`	الموظفون الذين لديهم `orders.view`	كل فعالية لها طلبات، لفلتر صفحة الطلبات
`GET`	`/api/admin/orders/:reference`	الموظفون الذين لديهم `orders.view`	طلب واحد: التذاكر والاستردادات والجدول الزمني للدفع ورابط إليه في لوحة المزوّد و`version` الخاص به
`GET`	`/api/admin/orders/:reference/refund-preview`	الموظفون الذين لديهم `refunds.create`	ما سيعيده استرداد `?tickets=TKT-1042-2,…`، لكل تذكرة
`POST`	`/api/admin/orders/:reference/refunds`	الموظفون الذين لديهم `refunds.create`	استرد تذاكر كاملة: `tickets` (من 1 إلى 8 أرقام مرجعية)، و`reason` (`customer_request` أو `event_cancelled` أو `duplicate_order` أو `event_changed` أو `other`)، و`acknowledged` (`true`) و`order_version`. يحتاج إلى `Idempotency-Key`. يجيب `202` مع الاسترداد `pending`
`POST`	`/api/admin/refunds/:id/retry`	الموظفون الذين لديهم `refunds.create`	أرسل استردادًا فاشلًا إلى المزوّد مرة أخرى
`POST`	`/api/admin/refunds/:id/restore`	الموظفون الذين لديهم `refunds.create`	أغلق استردادًا فاشلًا نهائيًا؛ فتعود تذاكره صالحة
`POST`	`/api/admin/tickets/:reference/reissue`	الموظفون الذين لديهم `tickets.manage`	رمز QR جديد لتذكرة صالحة؛ ويتوقف الرمز القديم عن العمل عند الباب
`POST`	`/api/admin/tickets/:reference/void`	الموظفون الذين لديهم `tickets.manage`	ألغِ تذكرة مجانية. التذكرة المدفوعة تجيب `409` مع `USE_REFUND`: فتُسترد بدلًا من ذلك

تُعلَّق تذاكره (refund_pending) بمجرد طلب الاسترداد، فيرفضها الباب. ويستقر الاسترداد حين يؤكده المزوّد، بعد ثوانٍ في المحاكي: فتُلغى التذاكر وتعود مقاعدها للبيع. والاسترداد الفاشل يُبقيها معلّقة إلى أن يُعاد أو يُستعاد، فتصبح صالحة من جديد. اقرأ الطلب مرة أخرى لترى أين وصل.

تسجيل الدخول عند الباب

الطريقة	المسار	من يحق له استدعاؤه	وظيفته
`GET`	`/api/admin/check-in/sessions`	الموظفون الذين لديهم `checkin.scan`	الجلسات التي يستطيع هذا العضو مسحها، من يوم مضى فصاعدًا، مع أعداد من دخلوا والمتوقعين وهل الأبواب مفتوحة
`GET`	`/api/admin/check-in/sessions/:code/summary`	الموظفون الذين لديهم `checkin.scan`	من دخلوا والمتوقعون والمتبقون، والتنبيهات المنتظرة
`GET`	`/api/admin/check-in/sessions/:code/scans`	الموظفون الذين لديهم `checkin.scan`	آخر عمليات المسح، كل منها `admitted` أو `eligible` أو `duplicate` أو `wrong_session` أو `void` أو `not_found`
`POST`	`/api/admin/check-in/sessions/:code/acknowledge`	الموظفون الذين لديهم `checkin.scan`	علّم تنبيهات الجلسة كمرئية
`POST`	`/api/admin/check-in/validate`	الموظفون الذين لديهم `checkin.scan`	`session_code` و`code`: ما قرأته الكاميرا، أو رقم مرجعي لتذكرة مكتوب مثل `TKT-1042-1`. يقول هل تستطيع التذكرة الدخول، دون أن يُدخلها
`POST`	`/api/admin/check-in/admit`	الموظفون الذين لديهم `checkin.scan`	الشيء نفسه مع `client_request_id` (UUID)، ويُدخل التذكرة. التذكرة التي دخلت بالفعل تجيب `409` مع `ALREADY_ADMITTED`، ومتى ومن فعل؛ ويُرفض `WRONG_SESSION` و`TICKET_VOID` أيضًا
`GET`	`/api/admin/session-staff`	الموظفون الذين لديهم `admins.edit`	أي موظفي تسجيل الدخول مُسندون إلى أي جلسات
`PUT`	`/api/admin/session-staff/:code`	الموظفون الذين لديهم `admins.edit`	حدّد موظفي باب الجلسة: `admin_ids`، مفصولة بفواصل

الأعضاء الذين يستطيعون تعديل الفعاليات أو نشرها يصلون إلى كل جلسة؛ وغيرهم إلى الجلسات المسندة إليهم فقط، وغيرها يجيب 403. ويستطيع كل عضو إجراء 120 فحصًا في الدقيقة.

النظرة العامة والتقارير والتصدير

الطريقة	المسار	من يحق له استدعاؤه	وظيفته
`GET`	`/api/admin/overview`	الموظفون الذين لديهم `overview.view`	النظرة العامة: الإجماليات وسلسلة المبيعات والمبيعات بحسب الفعالية والمزوّد والفئة، والباب المباشر، والفعاليات القادمة، وما يحتاج إلى انتباه. `range` (`last_7_days` أو `last_30_days` أو `this_month` أو `all`)، والقيمة الافتراضية `last_30_days`
`GET`	`/api/admin/reports`	الموظفون الذين لديهم `reports.view`	أرقام المبيعات نفسها، لـ `range`، أو `from` و`to`، واختياريًا `event` واحدة
`POST`	`/api/admin/reports/export`	الموظفون الذين لديهم `reports.export`	ابدأ ملف CSV: `kind` (`orders` أو `sales` أو `attendees`) و`filters` اختيارية. يجيب `202` مع `id` الخاص به
`GET`	`/api/admin/reports/exports/:id`	الموظفون الذين لديهم `reports.export`	أين وصل التصدير؛ وعند الجاهزية، `download_url` الخاص به
`GET`	`/api/admin/reports/exports/:id/download`	أي شخص يحمل `token` الرابط	ملف CSV. يعمل الرابط ساعة واحدة ويظهر مرة واحدة

تُكتب ملفات CSV في EXPORT_DIR في الخلفية، ويُبنى رابط التنزيل من PUBLIC_API_URL.

مساحة العمل والدفع وإعدادات الموقع

الطريقة	المسار	من يحق له استدعاؤه	وظيفته
`GET`	`/api/admin/workspace`	الموظفون الذين لديهم `settings.view`	مساحة العمل: الاسم وبريد الدعم والعملة والمنطقة الزمنية ورسوم الحجز (`fee_bps`) و`hold_seconds` و`max_per_order` (للقراءة فقط: هي أعمدة تُملأ من `back-end/src/database/seeders/data/settings.json`)، و`notification_settings`، وهي مفاتيح جرس إشعارات الفريق
`PATCH`	`/api/admin/workspace`	الموظفون الذين لديهم `settings.edit`	غيّر `name` أو `support_email` أو `currency` (`USD` أو `EUR` أو `GBP` أو `AED` أو `SAR`) أو `time_zone` أو `fee_bps` (من 0 إلى 2000، بأجزاء من مئة من النسبة المئوية؛ ويدفعها الحاضر دائمًا عند الدفع) أو `notification_settings` (`order_paid` و`refund_requested` و`checkin_alerts`)، مع `version` المحمَّل. تُقفل العملة متى باعت مساحة العمل (`CURRENCY_LOCKED`). وأي حقل آخر، ومنه `fee_payer` و`hold_seconds` و`max_per_order`، يجيب `400`
`GET`	`/api/admin/payment-providers`	الموظفون الذين لديهم `settings.view`	`configured` و`live` و`offered` لكل مزوّد. تبقى المفاتيح في `.env` الخاص بواجهة API ولا تُعاد أبدًا
`GET`	`/api/settings`	الموظفون الذين لديهم `settings.view`	كل إعدادات الموقع. `search` و`category` و`page` و`page_count`
`GET`	`/api/settings/:key`	الموظفون الذين لديهم `settings.view`	إعداد واحد بالمفتاح
`PATCH`	`/api/settings/:key`	الموظفون الذين لديهم `settings.edit`	غيّر قيمة إعداد واحد
`DELETE`	`/api/settings/:key`	الموظفون الذين لديهم `settings.edit`	احذف إعدادًا واحدًا

الفريق والأدوار

الطريقة	المسار	من يحق له استدعاؤه	وظيفته
`GET`	`/api/admins`	الموظفون الذين لديهم `admins.view`	فريق مساحة العمل. `email` و`name` و`phone` (يجب أن يطابق كل ما يُعطى)، و`page` و`page_count`
`GET`	`/api/admins/statistics`	الموظفون الذين لديهم `admins.view`	أعداد لقائمة الفريق
`GET`	`/api/admins/:id`	الموظفون الذين لديهم `admins.view`	عضو واحد، بالمعرّف أو اسم المستخدم
`POST`	`/api/admins`	الموظفون الذين لديهم `admins.create`	أضف عضوًا: `first_name` و`last_name` و`email` و`password` و`password_confirmation` (6 أحرف أو أكثر)، واختياريًا `phone`
`PATCH`	`/api/admins/:id`	الموظفون الذين لديهم `admins.edit`	غيّر عضوًا
`PATCH`	`/api/admins/:id/roles`	الموظفون الذين لديهم `admins.assign_roles`	حدّد أدوار عضو: `role_ids`
`DELETE`	`/api/admins/:id`	الموظفون الذين لديهم `admins.delete`	أخرج عضوًا من مساحة العمل الحالية. لا يُحذف الحساب نفسه إلا إذا كانت تلك آخر مساحة له؛ ويجيب `data.removed` بـ `workspace` أو `account`. وإزالة نفسك تجيب `403` مع `REMOVE_SELF`، وإزالة آخر مالك في مساحة العمل `409` مع `LAST_OWNER`
`PATCH`	`/api/admins/profile`	أي موظف مسجَّل الدخول	غيّر `first_name` أو `last_name` أو `email` أو `phone` أو `profile_picture` أو `country_id` الخاصة بالعضو المسجَّل دخوله. وأي `password` أو `role_ids` في الجسم يجيب `400`: فلكلمة المرور مسارها الخاص
`PATCH`	`/api/admins/profile/password`	أي موظف مسجَّل الدخول	غيّر كلمة مرور العضو المسجَّل دخوله نفسه: `current_password` و`password` و`password_confirmation`
`GET`	`/api/roles`	الموظفون الذين لديهم `roles.view`	الأدوار. `name` و`guard_name` و`created_from` و`created_to` و`page` و`page_count`
`GET`	`/api/roles/statistics`	الموظفون الذين لديهم `roles.view`	أعداد لقائمة الأدوار
`GET`	`/api/roles/select`	الموظفون الذين لديهم `roles.view`	معرّف كل دور واسمه، لقائمة الاختيار
`GET`	`/api/roles/permissions`	الموظفون الذين لديهم `roles.view`	كل صلاحية، مجمعة حسب المنطقة
`GET`	`/api/roles/:id`	الموظفون الذين لديهم `roles.view`	دور واحد بصلاحياته
`POST`	`/api/roles`	الموظفون الذين لديهم `roles.create`	أضف دورًا: `name`
`PUT`	`/api/roles/:id`	الموظفون الذين لديهم `roles.edit`	أعد تسمية دور: `name`
`POST`	`/api/roles/:id/permissions`	الموظفون الذين لديهم `roles.assign_permissions`	حدّد `permissions` الدور، بالاسم
`DELETE`	`/api/roles/:id`	الموظفون الذين لديهم `roles.delete`	حذف دور

الاستفسارات والإشعارات والملفات المرفوعة

الطريقة	المسار	من يحق له استدعاؤه	وظيفته
`GET`	`/api/leads`	الموظفون الذين لديهم `leads.view`	استفسارات نموذج التواصل، مع أعداد لكل حالة. `status` و`q` و`received_within_days` و`page` و`page_size`
`GET`	`/api/leads/:id`	الموظفون الذين لديهم `leads.view`	استفسار واحد
`PATCH`	`/api/leads/:id`	الموظفون الذين لديهم `leads.edit`	حدّد `status` (`new` أو `contacted` أو `closed`) أو `notes` أو `assigned_admin_id`
`GET`	`/api/notifications`	أي موظف مسجَّل الدخول	أحدث 30 إشعارًا للعضو المسجَّل دخوله
`PATCH`	`/api/notifications/read-all`	أي موظف مسجَّل الدخول	حدّدها كلها كمقروءة
`PATCH`	`/api/notifications/:id/read`	أي موظف مسجَّل الدخول	تعليم إشعار واحد كمقروء
`DELETE`	`/api/notifications/:id`	أي موظف مسجَّل الدخول	حذف إشعار واحد
`POST`	`/api/helpers/upload`	أي موظف مسجَّل الدخول	خزّن ملفًا (`file` متعدد الأجزاء، مع `path` للمجلد، و`for` لضبط الحجم المسبق مثل `venue` أو `cover` أو `logo` أو `profile`، و`type`). تُحوَّل الصور إلى ترميز جديد بعرض لا يزيد على 1920 بكسل؛ وتُقبل مقاطع الفيديو بصيغ MP4 أو WebM أو MOV أو M4V؛ بحد أقصى 150 ميغابايت. يجيب بعناوين الملف المخزَّن

تغطي الإشعارات الطلبات المدفوعة وطلبات الاسترداد وتنبيهات الباب والاستفسارات الجديدة ومفاهيم الأماكن المنتهية، وتُحفظ 30 يومًا. ليس للملف المرفوع صلاحية خاصة: ما يصير إليه الملف يفحصه المسار الذي يحفظه. وتذهب الملفات إلى حاوية R2 متى ضُبطت متغيراتها الخمسة، وإلى MEDIA_UPLOAD_DIR في غير ذلك.

الحدود لكل عنوان

المسار	الحد	المتغير
`POST /api/auth/login`, `POST /api/customer-auth/login`	10 محاولات دخول فاشلة كل 15 دقيقة، كل نوع يُحسب على حدة	`RATE_LIMIT_LOGIN`
`POST /api/customer-auth/register`	10 كل 10 دقائق	لا شيء
`POST /api/customer-auth/forgot-password`	5 كل 10 دقائق	لا شيء
`POST /api/leads`	5 كل 10 دقائق	لا شيء
`POST /api/admin/check-in/validate`, `/admit`	120 في الدقيقة لكل موظف	لا شيء
`POST /api/customer-auth/resend-verification`, `POST /api/orders/:reference/resend-email`	مرة في الدقيقة	لا شيء

الطلب الذي يتجاوز حدًّا يُجاب بـ 429. العدّادات محفوظة في ذاكرة واجهة API، لذلك يمسحها إعادة التشغيل. خلف وكيل عكسي، اضبط TRUST_PROXY ليُحسب كل زائر على عنوانه.