مرجع واجهة API

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

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

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

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

يحمل data النتيجة. وmessage جملة قصيرة تملؤها بعض عمليات الكتابة، بلغة الطلب، وتكون فارغة غير ذلك. الأسعار بالدولار الأمريكي الكامل، والتواريخ أيام تقويمية للشركة تُكتب YYYY-MM-DD.

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

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

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

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

الأخطاء

يحتفظ الفشل بالغلاف، مع success: false وحالة HTTP. وmessage جملة بلغة الطلب، وcode المفتاح غير المترجم خلفها، والرفض الذي يسمّي شيئًا يضيف القيم خلف جملته في details:

{
  "success": false,
  "data": null,
  "message": "Booking B0021 already holds some of these nights.",
  "code": "dates_taken",
  "details": { "held_by": "booking", "reference": "B0021" }
}

الجسم الذي يرفضه مسار التحقق يحمل code: "validation_failed" وerrors، مفهرسة باسم كل حقل الكامل:

{
  "success": false,
  "data": null,
  "message": "guest_email must be an email",
  "errors": { "guest_email": ["guest_email must be an email"] },
  "code": "validation_failed"
}

• اعتمد على code لا على الجملة، التي تتغير مع اللغة. وترفض الحجوزات والتوفر بأكواد مثل dates_taken وmin_nights وcapacity وcancellation_window_passed وawaiting_payment وpayment_method_unavailable، وللحد rate_limited.
• يظهر errors عند فشل التحقق، مع المشكلات تحت اسم الحقل كما كتبه الطلب (check_in وguest_email). ويُرفض الحقل المجهول في الجسم.
• المسار المحمي من دون رمز، أو برمز منتهي، يجيب بـ 401؛ والرمز الذي ينقصه الصلاحية يجيب بـ 403.
• الليالي المحتجزة بالفعل تُجاب بـ 409، وخطوة حجز من حالة خاطئة بـ 422، والطلب الذي يتجاوز حدًا بـ 429.

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

{ "data": [ ], "page": 1, "page_size": 6, "total": 12, "total_pages": 2 }

• تتصفح الإقامات والحجوزات والاستفسارات والتقييمات بـ page وpage_size: 6 إقامات في الصفحة في الموقع (24 على الأكثر)، و20 في لوحة التحكم (50 على الأكثر)، و10 حجوزات و20 استفسارًا (50 على الأكثر لكل منهما)، و8 تقييمات. وتعيد قوائم لوحة التحكم أيضًا counts لكل حالة.
• يتصفح المسؤولون والأدوار والإعدادات بـ page وpage_count (وتقبل الإعدادات page_size أيضًا)، 10 افتراضيًا و100 على الأكثر، وتجيب بـ { data, page, limit, total, totalPages }.
• يُتحقق من مرشحات إقامات الموقع: القيمة المجهولة تُرفض بـ 400 بدل تجاهلها، بينما يُتجاهل المفتاح الذي لا تقرؤه واجهة API، فيعمل الرابط المشارَك ذو المعاملات الزائدة.

اللغة

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

تسجيل الدخول

1. 01

   تسجيل دخول مسؤول

   الطرفيةنسخ

   curl -X POST http://localhost:8000/api/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"admin@hollina.example","password":"Admin@123"}'

   data.access_token هو الرمز، مع token_type بالقيمة Bearer والمسؤول بأدواره وصلاحياته. يدوم الرمز JWT_EXPIRATION، وهو 7d افتراضيًا، ويبلّغ expires_in عن تلك القيمة كما كُتبت. ويعيد GET /api/auth/me المسؤول المسجّل بأدواره وصلاحياته.
2. 02

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

   الطرفيةنسخ

   curl http://localhost:8000/api/bookings/manage -H "Authorization: Bearer YOUR_TOKEN"

• البريد غير المعروف وكلمة المرور الخاطئة يجيبان كلاهما بـ 401 مع الرسالة نفسها.
• عشر محاولات دخول فاشلة من عنوان واحد خلال 15 دقيقة تُجاب بـ 429 حتى يمضي 15 دقيقة على أقدم محاولة فاشلة (RATE_LIMIT_LOGIN). ولا تُحتسب عمليات الدخول الناجحة.
• لا يوجد مسار تسجيل ولا مسار تسجيل خروج: الحسابات تأتي من البيانات الأولية أو من إدارة المسؤولين، ويسجّل العميل الخروج بنسيان رمزه.
• ليس للضيوف حسابات. تأخذ مسارات حجز الضيف access_token الخاص بالحجز كـ ?token=، أو البريد الذي أُجري به كـ ?email=؛ والزوج الخاطئ يُجاب بـ 404.

الصلاحيات

تفحص مسارات لوحة التحكم صلاحية اسمها <area>.<action>. ويملك المسؤول كل صلاحية من كل دور لديه، والمسار الذي يسمّي عدة صلاحيات يقبل أيًا منها. والصلاحيات الـ 32 والدوران المضافان مسرودة في المسؤولون والأدوار والصلاحيات.

الإقامات في الموقع

الوجهات والأسئلة وإعدادات الشركة

الحجوزات

• client_token المكرر يعيد إيصال الحجز الأول بدل إنشاء ثانٍ، والحقل company المملوء يُعامل كروبوت: يبدو الجواب نفسه ولا يُخزَّن شيء.
• payment_method لا يسرده GET /api/payments/methods (PayPal مع Stripe وحده مضبوطًا، أو البطاقة مع PayPal وحده، أو الدفع عند الوصول وإعداده متوقف) يُجاب بـ 422 مع payment_method_unavailable، قبل كتابة أي شيء.
• تُفحص الليالي حين يُكتب الحجز: الليالي المحتجزة تُجاب بـ 409 مع dates_taken، وحد الإقامة الأدنى أو سعتها أو وصول في الماضي بـ 422 مع السبب.
• الطريقة المستضافة تُجاب بـ pending مع redirect_url إلى Stripe أو PayPal؛ ولا يؤكد الحجز إلا webhook المعالج أو التقاط PayPal.

أسئلة إلى المضيف

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

إدارة الإقامات

التقويم والتواريخ المحظورة

الحجوزات والاستفسارات والتقييمات

الوجهات والأسئلة والإعدادات

المسؤولون والأدوار

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

ليس للملف المرفوع صلاحية خاصة به: يفحص المسار الذي يحفظه ما يصير إليه الملف. تُحفظ الإشعارات 30 يومًا.

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

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

المساعد الذكي ومحادثاته

خادم MCP

التحديثات المباشرة عبر WebSocket

مسارات وضع العرض التجريبي