Maham Expo API - API Documentation

الميزات الرئيسية

Events Management

إدارة المعارض والفعاليات مع دعم الأقسام والمساحات المتعددة والأحداث المميزة.

Spaces & Approval

نظام مساحات مع مراجعة إدارية (موافقة/رفض) قبل النشر. دعم فلترة حسب الحالة وأقسام قابلة للتخصيص.

Visit Requests

طلبات زيارة المعارض مع نظام موافقة ورفض وتتبع الحالات الكامل.

Rental Requests

نظام إيجار متكامل مع إدارة المدفوعات والحالات المتعددة وتتبع الإيرادات.

Business Profiles

ملفات تجارية قابلة للتحقق مع نظام موافقة إدارية ورفع المستندات.

OTP & Email Auth

تسجيل دخول بطريقتين: رقم الجوال مع رمز OTP أو البريد الإلكتروني وكلمة المرور. مع وضع اختبار قابل للتفعيل.

الـ API العامة

Public API

نقاط الوصول المتاحة بدون مصادقة - تصفح الفعاليات والمساحات والخدمات

التصنيفات - Categories

GET /api/v1/categories قائمة التصنيفات public

GET /api/v1/categories/{category} تفاصيل تصنيف public

المدن - Cities

GET /api/v1/cities قائمة المدن public

GET /api/v1/cities/{city} تفاصيل مدينة public

الفعاليات - Events

GET /api/v1/events قائمة الفعاليات public

GET /api/v1/events/featured الفعاليات المميزة public

GET /api/v1/events/{event} تفاصيل فعالية public

GET /api/v1/events/{event}/spaces مساحات الفعالية public

GET /api/v1/events/{event}/sections أقسام الفعالية public

المساحات - Spaces

GET /api/v1/spaces/{space} تفاصيل مساحة public

الخدمات - Services

GET /api/v1/services قائمة الخدمات public

الإحصائيات - Statistics

GET /api/v1/statistics إحصائيات المنصة public

GET /api/v1/statistics/events إحصائيات الفعاليات public

GET /api/v1/statistics/spaces إحصائيات المساحات public

الرعاة - Sponsors (Public)

GET /api/v1/events/{event}/sponsors رعاة الفعالية public

GET /api/v1/events/{event}/sponsor-packages باقات الرعاية public

التقييمات - Ratings (Public)

GET /api/v1/ratings قائمة التقييمات public

GET /api/v1/ratings/summary ملخص التقييمات public

المحتوى - Pages, FAQs & Banners (Public)

GET /api/v1/pages قائمة الصفحات public

GET /api/v1/pages/{slug} عرض صفحة public

GET /api/v1/faqs قائمة الأسئلة الشائعة public

GET /api/v1/faqs/categories تصنيفات الأسئلة public

GET /api/v1/faqs/{faq} تفاصيل سؤال public

POST /api/v1/faqs/{faq}/helpful تقييم الإجابة public

GET /api/v1/banners قائمة البانرات public

POST /api/v1/banners/{banner}/click تسجيل نقرة public

أنواع النشاط التجاري - Business Activity Types (Public)

GET /api/v1/business-activity-types قائمة أنواع النشاط public

GET /api/v1/business-activity-types/{id} تفاصيل نوع نشاط public

واجهة المستخدم

Authenticated API

نقاط الوصول التي تتطلب مصادقة - الملف الشخصي، المفضلة، الإشعارات، الطلبات

المصادقة: جميع هذه الـ Endpoints تتطلب Header: Authorization: Bearer {token} - يتم التحقق عبر Auth Service

الملف التجاري - Business Profile

GET /api/v1/profile عرض الملف التجاري auth

POST /api/v1/profile إنشاء ملف تجاري auth

PUT /api/v1/profile تحديث الملف التجاري auth

المفضلة - Favorites

GET /api/v1/favorites قائمة المفضلة auth

POST /api/v1/favorites إضافة للمفضلة auth

DELETE /api/v1/favorites/{favorite} إزالة من المفضلة auth

الإشعارات - Notifications

GET /api/v1/notifications قائمة الإشعارات auth

GET /api/v1/notifications/unread-count عدد غير المقروءة auth

PUT /api/v1/notifications/{notification}/read تحديد كمقروء auth

PUT /api/v1/notifications/read-all قراءة الكل auth

تفضيلات الإشعارات - Notification Preferences

GET /api/v1/notifications/preferences عرض التفضيلات notification-preferences.view

PUT /api/v1/notifications/preferences تحديث التفضيلات notification-preferences.update

التقييمات - Ratings (Authenticated)

POST /api/v1/ratings إنشاء تقييم ratings.create

PUT /api/v1/ratings/{rating} تعديل تقييم ratings.update

DELETE /api/v1/ratings/{rating} حذف تقييم ratings.delete

تذاكر الدعم - Support Tickets

GET /api/v1/support-tickets قائمة التذاكر support-tickets.view

POST /api/v1/support-tickets إنشاء تذكرة support-tickets.create

GET /api/v1/support-tickets/{id} تفاصيل تذكرة support-tickets.view

POST /api/v1/support-tickets/{id}/reply الرد على تذكرة support-tickets.reply

PUT /api/v1/support-tickets/{id}/close إغلاق تذكرة support-tickets.close

PUT /api/v1/support-tickets/{id}/reopen إعادة فتح تذكرة support-tickets.create

الفواتير - Invoices (Own)

GET /api/v1/invoices قائمة الفواتير invoices.view

GET /api/v1/invoices/{invoice} تفاصيل فاتورة invoices.view

طلبات الزيارة - Visit Requests

GET /api/v1/visit-requests قائمة طلبات الزيارة auth

POST /api/v1/visit-requests إنشاء طلب زيارة auth

GET /api/v1/visit-requests/{visitRequest} تفاصيل طلب زيارة auth

PUT /api/v1/visit-requests/{visitRequest} تحديث طلب زيارة auth

DELETE /api/v1/visit-requests/{visitRequest} حذف طلب زيارة auth

طلبات الإيجار - Rental Requests

verified profile required

GET /api/v1/rental-requests قائمة طلبات الإيجار auth

POST /api/v1/rental-requests إنشاء طلب إيجار auth

GET /api/v1/rental-requests/{rentalRequest} تفاصيل طلب إيجار auth

PUT /api/v1/rental-requests/{rentalRequest} تحديث طلب إيجار auth

DELETE /api/v1/rental-requests/{rentalRequest} حذف طلب إيجار auth

ملاحظة: طلبات الإيجار تتطلب ملف تجاري موثق (verified business profile) قبل إنشاء الطلب

لوحة الإدارة

Admin API

نقاط الوصول الإدارية - تتطلب صلاحية admin أو super-admin

الصلاحيات: جميع هذه الـ Endpoints تتطلب دور admin أو super-admin بالإضافة للمصادقة

GET /api/v1/admin/dashboard إحصائيات لوحة التحكم admin

Query Parameters

spaces_period optional all|today|week|month|year

revenue_period optional all|today|week|month|year

event_id optional uuid - فلتر حسب الفعالية

Response 200

{
  "data": {
    "overview": {
      "total_revenue": 450000,
      "total_spaces": 122,
      "total_visit_requests": 4,
      "total_rental_requests": 3
    },
    "spaces": { /* by_status */ },
    "revenue": { /* by_payment_status */ },
    "visit_requests": { /* counts */ },
    "rental_requests": { /* counts */ }
  }
}

GET /api/v1/admin/statistics الإحصائيات — نفس بيانات لوحة التحكم admin

إدارة الفعاليات - Events Management

GET /api/v1/admin/events قائمة الفعاليات admin

POST /api/v1/admin/events إنشاء فعالية admin

GET /api/v1/admin/events/{event} تفاصيل فعالية admin

PUT /api/v1/admin/events/{event} تحديث فعالية admin

DELETE /api/v1/admin/events/{event} حذف فعالية admin

GET /api/v1/admin/events/{event}/sections أقسام الفعالية admin

POST /api/v1/admin/events/{event}/sections إنشاء قسم admin

GET /api/v1/admin/events/{event}/spaces مساحات الفعالية admin

POST /api/v1/admin/events/{event}/spaces إنشاء مساحة admin

إدارة الأقسام

GET /api/v1/admin/sections/{section} التفاصيل

PUT /api/v1/admin/sections/{section} تحديث

DELETE /api/v1/admin/sections/{section} حذف

إدارة المساحات

GET /api/v1/admin/spaces/{space} التفاصيل

PUT /api/v1/admin/spaces/{space} تحديث

DELETE /api/v1/admin/spaces/{space} حذف

PUT /api/v1/admin/spaces/{space}/approve الموافقة على المساحة

PUT /api/v1/admin/spaces/{space}/reject رفض المساحة (مع سبب)

إدارة الخدمات - Services Management

GET /api/v1/admin/services قائمة الخدمات admin

POST /api/v1/admin/services إنشاء خدمة admin

GET /api/v1/admin/services/{service} تفاصيل خدمة admin

PUT /api/v1/admin/services/{service} تحديث خدمة admin

DELETE /api/v1/admin/services/{service} حذف خدمة admin

إدارة طلبات الزيارة - Visit Requests Management

GET /api/v1/admin/visit-requests قائمة جميع الطلبات admin

GET /api/v1/admin/visit-requests/{visitRequest} تفاصيل طلب admin

PUT /api/v1/admin/visit-requests/{visitRequest}/approve قبول الطلب admin

PUT /api/v1/admin/visit-requests/{visitRequest}/reject رفض الطلب admin

إدارة طلبات الإيجار - Rental Requests Management

GET /api/v1/admin/rental-requests قائمة جميع الطلبات admin

GET /api/v1/admin/rental-requests/{rentalRequest} تفاصيل طلب admin

PUT /api/v1/admin/rental-requests/{rentalRequest}/approve قبول الطلب admin

PUT /api/v1/admin/rental-requests/{rentalRequest}/reject رفض الطلب admin

POST /api/v1/admin/rental-requests/{rentalRequest}/payment تسجيل دفعة admin

إدارة الملفات التجارية - Business Profiles Management

GET /api/v1/admin/profiles قائمة الملفات التجارية admin

GET /api/v1/admin/profiles/{profile} تفاصيل ملف تجاري admin

PUT /api/v1/admin/profiles/{profile}/approve قبول الملف admin

PUT /api/v1/admin/profiles/{profile}/reject رفض الملف admin

إدارة الرعاة - Sponsors Management

GET /api/v1/admin/sponsors قائمة الرعاة

POST /api/v1/admin/sponsors إنشاء راعي

GET /api/v1/admin/sponsors/{sponsor} تفاصيل راعي

PUT /api/v1/admin/sponsors/{sponsor} تحديث راعي

DELETE /api/v1/admin/sponsors/{sponsor} حذف راعي

PUT /api/v1/admin/sponsors/{sponsor}/approve قبول راعي

PUT /api/v1/admin/sponsors/{sponsor}/activate تفعيل راعي

PUT /api/v1/admin/sponsors/{sponsor}/suspend تعليق راعي

باقات الرعاية والعقود والمدفوعات - Sponsor Packages, Contracts, Payments, Benefits & Assets

GET /api/v1/admin/events/{event}/sponsor-packages باقات الفعالية

POST /api/v1/admin/events/{event}/sponsor-packages إنشاء باقة

GET /api/v1/admin/sponsor-packages/{id} تفاصيل باقة

PUT /api/v1/admin/sponsor-packages/{id} تحديث باقة

DELETE /api/v1/admin/sponsor-packages/{id} حذف باقة

GET /api/v1/admin/sponsor-contracts قائمة العقود

POST /api/v1/admin/sponsor-contracts إنشاء عقد

GET /api/v1/admin/sponsor-contracts/{id} تفاصيل عقد

PUT /api/v1/admin/sponsor-contracts/{id} تحديث عقد

PUT /api/v1/admin/sponsor-contracts/{id}/approve قبول عقد

PUT /api/v1/admin/sponsor-contracts/{id}/reject رفض عقد

PUT /api/v1/admin/sponsor-contracts/{id}/complete إتمام عقد

GET /api/v1/admin/sponsor-payments قائمة المدفوعات

POST /api/v1/admin/sponsor-payments إنشاء دفعة

GET /api/v1/admin/sponsor-payments/{id} تفاصيل دفعة

PUT /api/v1/admin/sponsor-payments/{id} تحديث دفعة

PUT /api/v1/admin/sponsor-payments/{id}/mark-paid تأكيد الدفع

GET /api/v1/admin/sponsor-benefits قائمة المزايا

POST /api/v1/admin/sponsor-benefits إنشاء ميزة

GET /api/v1/admin/sponsor-benefits/{id} تفاصيل ميزة

PUT /api/v1/admin/sponsor-benefits/{id} تحديث ميزة

PUT /api/v1/admin/sponsor-benefits/{id}/deliver تأكيد تسليم ميزة

GET /api/v1/admin/sponsor-assets قائمة ملفات الرعاة

GET /api/v1/admin/sponsor-assets/{id} تفاصيل ملف

PUT /api/v1/admin/sponsor-assets/{id}/approve قبول ملف

PUT /api/v1/admin/sponsor-assets/{id}/reject رفض ملف

التقييمات والتذاكر والعقود والفواتير - Ratings, Tickets, Contracts & Invoices

GET /api/v1/admin/ratings قائمة التقييمات ratings.view-all

GET /api/v1/admin/ratings/{rating} تفاصيل تقييم ratings.view-all

PUT /api/v1/admin/ratings/{rating}/approve قبول تقييم ratings.approve

PUT /api/v1/admin/ratings/{rating}/reject رفض تقييم ratings.reject

DELETE /api/v1/admin/ratings/{rating} حذف تقييم ratings.delete

GET /api/v1/admin/support-tickets قائمة التذاكر support-tickets.view-all

GET /api/v1/admin/support-tickets/{id} تفاصيل تذكرة support-tickets.view-all

PUT /api/v1/admin/support-tickets/{id}/assign تعيين موظف support-tickets.assign

POST /api/v1/admin/support-tickets/{id}/reply الرد support-tickets.reply

PUT /api/v1/admin/support-tickets/{id}/resolve حل التذكرة support-tickets.close

PUT /api/v1/admin/support-tickets/{id}/close إغلاق التذكرة support-tickets.close

DELETE /api/v1/admin/support-tickets/{id} حذف تذكرة support-tickets.delete

GET /api/v1/admin/rental-contracts قائمة العقود rental-contracts.view-all

POST /api/v1/admin/rental-contracts إنشاء عقد rental-contracts.create

GET /api/v1/admin/rental-contracts/{id} تفاصيل عقد rental-contracts.view-all

PUT /api/v1/admin/rental-contracts/{id} تحديث عقد rental-contracts.update

PUT /api/v1/admin/rental-contracts/{id}/approve قبول عقد rental-contracts.approve

PUT /api/v1/admin/rental-contracts/{id}/reject رفض عقد rental-contracts.reject

PUT /api/v1/admin/rental-contracts/{id}/terminate إنهاء عقد rental-contracts.terminate

GET /api/v1/admin/invoices قائمة الفواتير invoices.view-all

POST /api/v1/admin/invoices إنشاء فاتورة invoices.create

GET /api/v1/admin/invoices/{invoice} تفاصيل فاتورة invoices.view-all

PUT /api/v1/admin/invoices/{invoice} تحديث فاتورة invoices.update

PUT /api/v1/admin/invoices/{invoice}/issue إصدار فاتورة invoices.issue

PUT /api/v1/admin/invoices/{invoice}/mark-paid تأكيد الدفع invoices.mark-paid

PUT /api/v1/admin/invoices/{invoice}/cancel إلغاء فاتورة invoices.cancel

إدارة المحتوى - Pages, FAQs & Banners Management

GET /api/v1/admin/pages قائمة الصفحات pages.view

POST /api/v1/admin/pages إنشاء صفحة pages.create

GET /api/v1/admin/pages/{page} تفاصيل صفحة pages.view

PUT /api/v1/admin/pages/{page} تحديث صفحة pages.update

DELETE /api/v1/admin/pages/{page} حذف صفحة pages.delete

GET /api/v1/admin/faqs قائمة الأسئلة faqs.view

POST /api/v1/admin/faqs إنشاء سؤال faqs.create

GET /api/v1/admin/faqs/{faq} تفاصيل سؤال faqs.view

PUT /api/v1/admin/faqs/{faq} تحديث سؤال faqs.update

DELETE /api/v1/admin/faqs/{faq} حذف سؤال faqs.delete

GET /api/v1/admin/banners قائمة البانرات banners.view

POST /api/v1/admin/banners إنشاء بانر banners.create

GET /api/v1/admin/banners/{banner} تفاصيل بانر banners.view

PUT /api/v1/admin/banners/{banner} تحديث بانر banners.update

DELETE /api/v1/admin/banners/{banner} حذف بانر banners.delete

أنواع الأعضاء والنشاط التجاري - Member Types & Business Activity Types (Admin)

GET /api/v1/manage/member-types قائمة أنواع الأعضاء member-types.view

POST /api/v1/manage/member-types إنشاء نوع عضو member-types.create

GET /api/v1/manage/member-types/{id} تفاصيل نوع عضو member-types.view

PUT /api/v1/manage/member-types/{id} تحديث نوع عضو member-types.update

DELETE /api/v1/manage/member-types/{id} حذف نوع عضو member-types.delete

GET /api/v1/manage/business-activity-types قائمة أنواع النشاط business-activity-types.view

POST /api/v1/manage/business-activity-types إنشاء نوع نشاط business-activity-types.create

GET /api/v1/manage/business-activity-types/{id} تفاصيل نوع نشاط business-activity-types.view

PUT /api/v1/manage/business-activity-types/{id} تحديث نوع نشاط business-activity-types.update

DELETE /api/v1/manage/business-activity-types/{id} حذف نوع نشاط business-activity-types.delete

إدارة المستثمرين - Investors Management (Admin)

GET /api/v1/manage/investors قائمة المستثمرين profiles.view-all

POST /api/v1/manage/investors إنشاء مستثمر profiles.approve

GET /api/v1/manage/investors/{investor} تفاصيل مستثمر profiles.view-all

PUT /api/v1/manage/investors/{investor} تحديث مستثمر profiles.approve

DELETE /api/v1/manage/investors/{investor} حذف مستثمر profiles.approve

إدارة التجار - Merchants Management (Admin)

GET /api/v1/manage/merchants قائمة التجار profiles.view-all

POST /api/v1/manage/merchants إنشاء تاجر profiles.approve

GET /api/v1/manage/merchants/{merchant} تفاصيل تاجر profiles.view-all

PUT /api/v1/manage/merchants/{merchant} تحديث تاجر profiles.approve

DELETE /api/v1/manage/merchants/{merchant} حذف تاجر profiles.approve

عملاء الرعاة المحتملون - Sponsor Leads (Admin)

GET /api/v1/manage/sponsor-leads قائمة العملاء المحتملين sponsor-leads.view-all

POST /api/v1/manage/sponsor-leads إنشاء عميل محتمل sponsor-leads.create

GET /api/v1/manage/sponsor-leads/{id} تفاصيل عميل sponsor-leads.view-all

PUT /api/v1/manage/sponsor-leads/{id} تحديث عميل sponsor-leads.update

DELETE /api/v1/manage/sponsor-leads/{id} حذف عميل sponsor-leads.delete

تسليمات الرعاية - Sponsor Deliverables (Admin)

GET /api/v1/manage/sponsor-deliverables قائمة التسليمات sponsor-deliverables.view-all

POST /api/v1/manage/sponsor-deliverables إنشاء تسليم sponsor-deliverables.create

GET /api/v1/manage/sponsor-deliverables/{id} تفاصيل تسليم sponsor-deliverables.view-all

PUT /api/v1/manage/sponsor-deliverables/{id} تحديث تسليم sponsor-deliverables.update

DELETE /api/v1/manage/sponsor-deliverables/{id} حذف تسليم sponsor-deliverables.delete

PUT /api/v1/manage/sponsor-deliverables/{id}/approve اعتماد تسليم sponsor-deliverables.approve

PUT /api/v1/manage/sponsor-deliverables/{id}/reject رفض تسليم sponsor-deliverables.approve

واجهة المشرف

Supervisor API

نقاط الوصول للمشرف - تحكم كامل بجميع العمليات (نفس صلاحيات المدير)

الصلاحيات: المشرف لديه تحكم كامل — نفس صلاحيات admin (إنشاء، تعديل، حذف، اعتماد، رفض)

لوحة التحكم واستعراض البيانات - Dashboard & Browse (Read-Only)

GET /api/v1/supervisor/dashboard إحصائيات لوحة التحكم supervisor

GET /api/v1/supervisor/statistics الإحصائيات supervisor

GET /api/v1/supervisor/events قائمة الفعاليات supervisor

GET /api/v1/supervisor/events/{event} تفاصيل فعالية supervisor

GET /api/v1/supervisor/events/{event}/sections أقسام الفعالية supervisor

GET /api/v1/supervisor/events/{event}/spaces مساحات الفعالية supervisor

GET /api/v1/supervisor/sections/{section} تفاصيل قسم supervisor

GET /api/v1/supervisor/spaces/{space} تفاصيل مساحة supervisor

GET /api/v1/supervisor/services قائمة الخدمات supervisor

GET /api/v1/supervisor/services/{service} تفاصيل خدمة supervisor

إدارة الطلبات - Request Management (بعد موافقة المستثمر)

GET /api/v1/supervisor/visit-requests قائمة طلبات الزيارة supervisor

GET /api/v1/supervisor/visit-requests/{id} تفاصيل طلب زيارة supervisor

PUT /api/v1/supervisor/visit-requests/{id}/approve قبول طلب زيارة supervisor

PUT /api/v1/supervisor/visit-requests/{id}/reject رفض طلب زيارة supervisor

GET /api/v1/supervisor/rental-requests قائمة طلبات الإيجار supervisor

GET /api/v1/supervisor/rental-requests/{id} تفاصيل طلب إيجار supervisor

PUT /api/v1/supervisor/rental-requests/{id}/approve قبول طلب إيجار supervisor

PUT /api/v1/supervisor/rental-requests/{id}/reject رفض طلب إيجار supervisor

POST /api/v1/supervisor/rental-requests/{id}/payment تسجيل دفعة supervisor

إدارة الملفات التجارية - Profiles Management

GET /api/v1/supervisor/profiles قائمة الملفات التجارية supervisor

GET /api/v1/supervisor/profiles/{id} تفاصيل ملف تجاري supervisor

PUT /api/v1/supervisor/profiles/{id}/approve قبول الملف supervisor

PUT /api/v1/supervisor/profiles/{id}/reject رفض الملف supervisor

الرعاة والعقود - Sponsors & Contracts (Supervisor)

GET /api/v1/supervisor/sponsors قائمة الرعاة

GET /api/v1/supervisor/sponsors/{sponsor} تفاصيل راعي

GET /api/v1/supervisor/sponsor-contracts قائمة العقود

GET /api/v1/supervisor/sponsor-contracts/{id} تفاصيل عقد

PUT /api/v1/supervisor/sponsor-contracts/{id}/approve قبول عقد

PUT /api/v1/supervisor/sponsor-contracts/{id}/reject رفض عقد

التذاكر وعقود الإيجار - Tickets & Rental Contracts (Supervisor)

GET /api/v1/supervisor/support-tickets قائمة التذاكر

GET /api/v1/supervisor/support-tickets/{id} تفاصيل تذكرة

POST /api/v1/supervisor/support-tickets/{id}/reply الرد على تذكرة

GET /api/v1/supervisor/rental-contracts قائمة العقود

GET /api/v1/supervisor/rental-contracts/{id} تفاصيل عقد

واجهة المدير العام

Super Admin API

صلاحيات كاملة - إدارة النظام والتصنيفات والمدن والمستخدمين والإعدادات

الصلاحيات: تتطلب دور super-admin فقط - أعلى مستوى صلاحيات

GET /api/v1/super-admin/dashboard لوحة تحكم مع إحصائيات النظام والتحليلات super-admin

Query Params: analytics_period, spaces_period, revenue_period (all|today|week|month|year) + event_id

GET /api/v1/super-admin/statistics الإحصائيات — نفس بيانات لوحة التحكم super-admin

إدارة التصنيفات - Categories CRUD

GET /api/v1/super-admin/categories قائمة التصنيفات super-admin

POST /api/v1/super-admin/categories إنشاء تصنيف super-admin

GET /api/v1/super-admin/categories/{id} تفاصيل تصنيف super-admin

PUT /api/v1/super-admin/categories/{id} تحديث تصنيف super-admin

DELETE /api/v1/super-admin/categories/{id} حذف تصنيف super-admin

إدارة المدن - Cities CRUD

GET /api/v1/super-admin/cities قائمة المدن super-admin

POST /api/v1/super-admin/cities إنشاء مدينة super-admin

GET /api/v1/super-admin/cities/{id} تفاصيل مدينة super-admin

PUT /api/v1/super-admin/cities/{id} تحديث مدينة super-admin

DELETE /api/v1/super-admin/cities/{id} حذف مدينة super-admin

إدارة المستخدمين - Users

GET /api/v1/super-admin/users القائمة

GET /api/v1/super-admin/users/{id} التفاصيل

PUT /api/v1/super-admin/users/{id}/approve قبول

PUT /api/v1/super-admin/users/{id}/reject رفض

PUT /api/v1/super-admin/users/{id}/suspend تعليق

إعدادات النظام - Settings

GET /api/v1/super-admin/settings جميع الإعدادات

GET /api/v1/super-admin/settings/{key} إعداد محدد

PUT /api/v1/super-admin/settings تحديث الإعدادات

واجهة المستثمر

Investor API

إدارة المساحات الخاصة، الموافقة على الطلبات، تتبع الإيرادات والمدفوعات

الصلاحيات: تتطلب دور investor

لوحة التحكم وإدارة المساحات - Dashboard & Spaces

GET /api/v1/investor/dashboard لوحة التحكم investor

GET /api/v1/investor/statistics الإحصائيات investor

GET /api/v1/investor/spaces قائمة مساحاتي investor

POST /api/v1/investor/spaces إنشاء مساحة investor

GET /api/v1/investor/spaces/{id} تفاصيل مساحة investor

PUT /api/v1/investor/spaces/{id} تحديث مساحة investor

DELETE /api/v1/investor/spaces/{id} حذف مساحة investor

POST /api/v1/investor/spaces/{id}/services إضافة خدمات investor

DELETE /api/v1/investor/spaces/{id}/services إزالة خدمات investor

الطلبات والمدفوعات - Requests & Payments

GET /api/v1/investor/rental-requests طلبات الإيجار investor

GET /api/v1/investor/rental-requests/pending-count عدد المعلّقة investor

GET /api/v1/investor/rental-requests/{id} تفاصيل طلب إيجار investor

PUT /api/v1/investor/rental-requests/{id}/approve قبول طلب إيجار investor

PUT /api/v1/investor/rental-requests/{id}/reject رفض طلب إيجار investor

GET /api/v1/investor/visit-requests طلبات الزيارة investor

GET /api/v1/investor/visit-requests/pending-count عدد المعلّقة investor

GET /api/v1/investor/visit-requests/{id} تفاصيل طلب زيارة investor

PUT /api/v1/investor/visit-requests/{id}/approve قبول طلب زيارة investor

PUT /api/v1/investor/visit-requests/{id}/reject رفض طلب زيارة investor

GET /api/v1/investor/payments سجل المدفوعات investor

GET /api/v1/investor/payments/summary ملخص الإيرادات investor

GET /api/v1/investor/payments/{id} تفاصيل دفعة investor

ملاحظة: موافقة المستثمر هي الخطوة الأولى - بعدها يحتاج الطلب موافقة المشرف/الأدمن

عقود الإيجار - Rental Contracts (Investor)

GET /api/v1/investor/rental-contracts قائمة العقود investor

GET /api/v1/investor/rental-contracts/{id} تفاصيل عقد investor

PUT /api/v1/investor/rental-contracts/{id}/sign توقيع العقد investor

فريق العمل - Team Members (Investor)

GET /api/v1/my/investor-team/member-types أنواع الأعضاء investor

GET /api/v1/my/investor-team قائمة الفريق investor

POST /api/v1/my/investor-team إضافة عضو investor

GET /api/v1/my/investor-team/{id} تفاصيل عضو investor

PUT /api/v1/my/investor-team/{id} تحديث عضو investor

DELETE /api/v1/my/investor-team/{id} حذف عضو investor

واجهة الراعي

Sponsor API

خدمة ذاتية للرعاة - إدارة العقود والمدفوعات والملفات والتعرض

الصلاحيات: تتطلب دور sponsor

GET /api/v1/sponsor/dashboard لوحة التحكم sponsor

GET /api/v1/sponsor/contracts قائمة العقود sponsor

GET /api/v1/sponsor/contracts/{id} تفاصيل عقد sponsor

PUT /api/v1/sponsor/contracts/{id}/sign توقيع العقد sponsor

GET /api/v1/sponsor/payments قائمة المدفوعات sponsor

GET /api/v1/sponsor/payments/{id} تفاصيل دفعة sponsor

POST /api/v1/sponsor/payments/{id}/proof رفع إثبات دفع sponsor

GET /api/v1/sponsor/assets قائمة الملفات sponsor

POST /api/v1/sponsor/assets رفع ملف sponsor

GET /api/v1/sponsor/assets/{id} تفاصيل ملف sponsor

PUT /api/v1/sponsor/assets/{id} تحديث ملف sponsor

DELETE /api/v1/sponsor/assets/{id} حذف ملف sponsor

GET /api/v1/sponsor/exposure تقرير التعرض sponsor

GET /api/v1/my/sponsor-leads عملائي المحتملون sponsor

GET /api/v1/my/sponsor-leads/{id} تفاصيل عميل محتمل sponsor

GET /api/v1/my/sponsor-deliverables تسليماتي sponsor

GET /api/v1/my/sponsor-deliverables/{id} تفاصيل تسليم sponsor

POST /api/v1/my/sponsor-deliverables/{id}/upload رفع ملف تسليم sponsor

واجهة التاجر

Merchant API

استعراض الفعاليات والمساحات والخدمات، تقديم طلبات الزيارة والإيجار

الصلاحيات: تتطلب دور merchant - طلبات الإيجار تتطلب ملف تجاري موثق

لوحة التحكم واستعراض البيانات - Dashboard & Browse

GET /api/v1/merchant/dashboard لوحة التحكم merchant

GET /api/v1/merchant/statistics الإحصائيات merchant

GET /api/v1/merchant/events قائمة الفعاليات merchant

GET /api/v1/merchant/events/{id} تفاصيل فعالية merchant

GET /api/v1/merchant/events/{id}/sections أقسام الفعالية merchant

GET /api/v1/merchant/events/{id}/spaces مساحات الفعالية merchant

GET /api/v1/merchant/spaces تصفح المساحات merchant

GET /api/v1/merchant/spaces/{id} تفاصيل مساحة merchant

GET /api/v1/merchant/services قائمة الخدمات merchant

GET /api/v1/merchant/services/{id} تفاصيل خدمة merchant

طلبات الزيارة والإيجار - Visit & Rental Requests

GET /api/v1/merchant/visit-requests طلبات الزيارة merchant

POST /api/v1/merchant/visit-requests طلب زيارة جديد merchant

GET /api/v1/merchant/visit-requests/{id} تفاصيل طلب merchant

PUT /api/v1/merchant/visit-requests/{id} تحديث الطلب merchant

DELETE /api/v1/merchant/visit-requests/{id} إلغاء الطلب merchant

GET /api/v1/merchant/rental-requests طلبات الإيجار merchant

POST /api/v1/merchant/rental-requests طلب إيجار جديد merchant

GET /api/v1/merchant/rental-requests/{id} تفاصيل طلب merchant

PUT /api/v1/merchant/rental-requests/{id} تحديث الطلب merchant

DELETE /api/v1/merchant/rental-requests/{id} إلغاء الطلب merchant

ملاحظة: طلبات الإيجار تتطلب ملف تجاري موثق وتمر بموافقة المستثمر ثم المشرف/الأدمن

عقود الإيجار - Rental Contracts (Merchant)

GET /api/v1/merchant/rental-contracts قائمة العقود merchant

GET /api/v1/merchant/rental-contracts/{id} تفاصيل عقد merchant

PUT /api/v1/merchant/rental-contracts/{id}/sign توقيع العقد merchant

فريق العمل - Team Members (Merchant)

GET /api/v1/my/merchant-team/member-types أنواع الأعضاء merchant

GET /api/v1/my/merchant-team قائمة الفريق merchant

POST /api/v1/my/merchant-team إضافة عضو merchant

GET /api/v1/my/merchant-team/{id} تفاصيل عضو merchant

PUT /api/v1/my/merchant-team/{id} تحديث عضو merchant

DELETE /api/v1/my/merchant-team/{id} حذف عضو merchant

طرق تسجيل الدخول

Authentication

المنصة تدعم طريقتين لتسجيل الدخول عبر Auth Service

رقم الجوال + رمز OTP

الطريقة الرئيسية - عبر SMS أو WhatsApp

1

إرسال رمز OTP

POST /api/v1/auth/otp/send

أرسل phone (مثال: +966500000000)

2

التحقق من الرمز

POST /api/v1/auth/otp/verify

أرسل phone + code (6 أرقام)

→ إذا المستخدم موجود: يرجع JWT Token مباشرة

→ إذا مستخدم جديد: يرجع registration_token

3

إكمال التسجيل (مستخدم جديد فقط)

POST /api/v1/auth/otp/complete-registration

أرسل registration_token + name + user_type required (merchant | investor | sponsor)

🔌 المزود: Authentica (SMS + WhatsApp) — OTP_TEST_MODE مفعل حالياً، الرمز 123456

البريد الإلكتروني + كلمة المرور

للوحة التحكم والمستخدمين الإداريين

1

تسجيل الدخول

POST /api/v1/auth/login

أرسل identifier (البريد أو الجوال) + password

→ يرجع JWT Token + بيانات المستخدم

2

استخدام التوكن

أضف الهيدر في كل طلب:

Authorization: Bearer {token}

3

تجديد التوكن

POST /api/v1/auth/refresh

التوكن صالح لمدة ساعة - جدده قبل انتهائه

ملاحظة: جميع endpoints المصادقة على Auth Service: https://auth-service-api.mahamexpo.sa

GET /api/v1/auth-mode — يرجع طريقة المصادقة المفعّلة حالياً

{
  "success": true,
  "data": {
    "auth_mode": "phone_and_otp",
    "available_modes": ["phone_and_otp", "email_and_password", "both"]
  }
}

طريقة التسجيل

Registration Flow

يمكن التسجيل في المنصة بطريقتين: التسجيل العادي أو عبر رمز التحقق OTP

1

التسجيل العادي

Standard Registration — الاسم + رقم الجوال

①

التسجيل

POST /api/v1/register — أرسل الاسم ورقم الجوال. الإيميل وكلمة المرور اختياريين. إذا لم ترسل كلمة مرور سيتم استخدام رقم الجوال ككلمة مرور.

②

تسجيل الدخول

POST /api/v1/login — سجّل بالجوال وكلمة المرور

# التسجيل العادي
curl -X POST https://auth-service-api.mahamexpo.sa/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "أحمد",
    "phone": "0501234567"
  }'

# كلمة المرور = رقم الجوال
curl -X POST https://auth-service-api.mahamexpo.sa/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "0501234567",
    "password": "0501234567"
  }'

2

التسجيل عبر OTP

OTP Registration — رقم الجوال + رمز التحقق

①

طلب OTP

POST /api/v1/otp/send — أرسل رقم الجوال. يصلك رمز تحقق عبر SMS (في وضع الاختبار الرمز دائماً 123456)

②

تأكيد OTP

POST /api/v1/otp/verify — أرسل الرقم + الرمز. إذا المستخدم جديد يتم تسجيله تلقائياً وكلمة المرور = رقم الجوال

# إرسال رمز التحقق
curl -X POST https://auth-service-api.mahamexpo.sa/api/v1/otp/send \
  -H "Content-Type: application/json" \
  -d '{"phone": "0501234567"}'

# تأكيد الرمز (والتسجيل التلقائي)
curl -X POST https://auth-service-api.mahamexpo.sa/api/v1/otp/verify \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "0501234567",
    "otp": "123456"
  }'

ملاحظة: في وضع الاختبار (sms_test_mode)، رمز OTP دائماً 123456

ملاحظات مهمة عن التسجيل

✓

الإيميل اختياري — يمكنك التسجيل بدون إيميل

✓

كلمة المرور الافتراضية — إذا لم تحدد كلمة مرور، سيتم استخدام رقم الجوال

✓

التسجيل التلقائي — عبر OTP، إذا الرقم جديد يتم إنشاء حساب تلقائياً

البدء السريع

Quick Start

أمثلة سريعة للبدء باستخدام الـ API

Browse Events & Featured

# قائمة الفعاليات
curl https://expo-service-api.mahamexpo.sa/api/v1/events \
  -H "Accept: application/json" \
  -H "Accept-Language: ar"

# الفعاليات المميزة
curl https://expo-service-api.mahamexpo.sa/api/v1/events/featured \
  -H "Accept: application/json"

# تفاصيل فعالية مع المساحات
curl https://expo-service-api.mahamexpo.sa/api/v1/events/{event_id}/spaces \
  -H "Accept: application/json"

Create Visit Request

curl -X POST https://expo-service-api.mahamexpo.sa/api/v1/visit-requests \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "event_id": "event-uuid-here",
    "visit_date": "2025-06-15",
    "visitors_count": 3,
    "notes": "نرغب في زيارة المعرض"
  }'

Create Rental Request (Requires Verified Profile)

curl -X POST https://expo-service-api.mahamexpo.sa/api/v1/rental-requests \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "space_id": "space-uuid-here",
    "start_date": "2025-06-01",
    "end_date": "2025-06-30",
    "notes": "نريد استئجار المساحة للمعرض"
  }'

Admin Dashboard Statistics

# إحصائيات المنصة (عامة - بدون مصادقة)
curl https://expo-service-api.mahamexpo.sa/api/v1/statistics

# إحصائيات الفعاليات (عامة)
curl https://expo-service-api.mahamexpo.sa/api/v1/statistics/events

# إحصائيات المساحات (عامة)
curl https://expo-service-api.mahamexpo.sa/api/v1/statistics/spaces

# إحصائيات الأدمن (تتطلب مصادقة)
curl https://expo-service-api.mahamexpo.sa/api/v1/manage/statistics \
  -H "Authorization: Bearer {admin-token}"

# لوحة تحكم الأدمن حسب الفترة
curl "https://expo-service-api.mahamexpo.sa/api/v1/manage/dashboard?spaces_period=month&revenue_period=week" \
  -H "Authorization: Bearer {admin-token}"

متغيرات البيئة

Environment Variables

جميع المتغيرات المطلوبة والاختيارية لتشغيل خدمة المعرض Expo API

Required - مطلوبة

يجب تعيينها

APP_KEY مفتاح التشفير الرئيسي للتطبيق php artisan key:generate --show required

DB_PASSWORD كلمة سر قاعدة البيانات MySQL required

Optional - اختيارية

لها قيم افتراضية

Application & Database

APP_NAME Maham Expo API اسم التطبيق optional

APP_ENV production بيئة التشغيل optional

APP_DEBUG false وضع التصحيح optional

APP_URL https://expo-service-api.mahamexpo.sa رابط التطبيق الرئيسي optional

APP_LOCALE ar اللغة الافتراضية optional

DB_CONNECTION mysql نوع قاعدة البيانات optional

DB_HOST expo-mysql مضيف قاعدة البيانات optional

DB_PORT 3306 منفذ قاعدة البيانات optional

DB_DATABASE maham_expo_api اسم قاعدة البيانات optional

DB_USERNAME expo_user مستخدم قاعدة البيانات optional

Redis & Cache & Queue

REDIS_HOST expo-redis مضيف Redis optional

REDIS_PORT 6379 منفذ Redis optional

REDIS_PASSWORD (empty) كلمة سر Redis optional

CACHE_STORE redis محرك التخزين المؤقت optional

CACHE_PREFIX expo_ بادئة مفاتيح الكاش optional

QUEUE_CONNECTION redis محرك قائمة المهام optional

SESSION_DRIVER redis محرك الجلسات optional

SESSION_LIFETIME 120 عمر الجلسة (دقائق) optional

Auth Service Connection - اتصال خدمة المصادقة

AUTH_SERVICE_URL http://auth-service رابط خدمة المصادقة الداخلي optional

AUTH_SERVICE_TIMEOUT 10 مهلة الاتصال بخدمة المصادقة (ثواني) optional

AUTH_SERVICE_CACHE_TTL 300 مدة تخزين بيانات المصادقة مؤقتاً (ثواني) optional

Service & Security

SERVICE_NAME expo-api اسم الخدمة optional

SERVICE_VERSION 1.0.0 إصدار الخدمة optional

RATE_LIMIT_PER_MINUTE 60 حد الطلبات في الدقيقة optional

BCRYPT_ROUNDS 12 جولات تشفير كلمات المرور optional

Logging & Mail

LOG_CHANNEL stack قناة التسجيل optional

LOG_LEVEL warning مستوى التسجيل optional

MAIL_MAILER log محرك البريد (log, smtp, mailgun) optional

MAIL_HOST (empty) مضيف SMTP optional

MAIL_PORT 587 منفذ SMTP optional

MAIL_USERNAME (empty) مستخدم SMTP optional

MAIL_PASSWORD (empty) كلمة سر SMTP optional

MAIL_ENCRYPTION tls تشفير البريد optional

MAIL_FROM_ADDRESS noreply@mahamexpo.sa عنوان المرسل optional

FILESYSTEM_DISK local نظام تخزين الملفات optional

منصة المعارض والفعاليات