نُزُل التوثيق · نُزُل

خاص بـ: الحزمة الكاملة · واجهة API

مرجع الـ API

كل نقاط واجهة نُزُل البرمجية، بصلاحياتها وأجوبتها.

كل النقاط تستقبل JSON وتعيده. المبالغ بأصغر وحدة للعملة (البيسة للريال العُماني)، والتواريخ بصيغة YYYY-MM-DD. وشكل الخطأ:

{ "error": { "code": "unavailable", "message": "Some of these nights are already booked.", "detail": { "nights": ["2026-11-06"] } } }
الحالة متى
‏400 bad_json جسم الطلب ليس JSON
‏401 unauthorized نقطة من اللوحة دون جلسة
‏403 forbidden الدور لا يملك الصلاحية
‏404 not_found عنصر غير موجود، أو خارج إقامات المضيف
‏409 رفضته قاعدة: unavailable وbad_transition وtoo_early وalready_requested وlast_owner وhas_bookings...
‏422 validation حقل ناقص أو خاطئ (الرسالة تذكره)، وكذلك قواعد السعر مثل min_nights
‏429 rate_limited طلبات كثيرة من هذا الزائر
‏502/503 مشكلة لدى مزوّد الدفع أو الذكاء الاصطناعي، أو الذكاء الاصطناعي غير مُعدّ (ai_disabled)

النقاط العامة

الطريقة والمسار ماذا تفعل
GET /api/stays الإقامات. المعاملات: destination، وtype (CHALET وVILLA وCABIN وBEACH_HOUSE وDESERT_CAMP)، وguests، وcheckIn مع checkOut، وminPrice/maxPrice (بالريال لليلة)، وamenities=pool,wifi، وslugs=a,b، وsort (recommended وprice_asc وprice_desc وrating وguests). مع التواريخ: المتاحة فقط، ومع كل منها quote وperNight
GET /api/stays/{slug} إقامة واحدة بمواسمها، مع تقييماتها المنشورة
GET /api/stays/{slug}/availability?from=&days= taken: الليالي المحجوزة أو المغلقة في النافذة (120 يوماً كحد أقصى)
GET /api/stays/{slug}/quote?checkIn=&checkOut=&guests= quote: ‏lines (سطر لكل ليلة بسعرها وموسمها)، وnightsTotal وcleaningFee وtax وtotal وminNights
GET /api/destinations الوجهات مع عدد إقاماتها وأقل سعر
POST /api/bookings {stayId, checkIn, checkOut, guests, guestName, email, phone, country, notes, paymentMethod: "CARD" أو "ON_ARRIVAL", locale, acceptTerms: true} ← 201 {code, status, payUrl?}
GET /api/bookings/{code} التأكيد: الإقامة والتواريخ والمجموع والحالة (دون بيانات التواصل)
POST /api/bookings/lookup {code, contact} (بريد أو هاتف) ← الحجز ببيانات تواصل مخفية جزئياً، وأسعار الليالي، ورمز الباب حين يحين وقته، وcanCancel وcanReview والسجل
POST /api/bookings/cancel {code, contact, reason} ← طلب إلغاء
POST /api/reviews {code, contact, rating 1-5, text} لإقامة مكتملة، وتقييم واحد لكل حجز
POST /api/inquiries {name, email, phone?, stayId? (المعرّف أو slug), checkIn?, checkOut?, guests?, message, locale}
GET /api/payments/thawani/return?booking= حيث تعيد ثواني الضيف، ويُتحقق فيه من الدفع لدى ثواني

مثال:

curl "http://localhost:3304/api/stays/juniper-cabin/quote?checkIn=2026-11-05&checkOut=2026-11-08&guests=2"

الجلسة

الطريقة والمسار ماذا تفعل
POST /api/auth/login {email, password} ← يضبط ملف nuzul_session (‏httpOnly، لمدة 12 ساعة)
POST /api/auth/logout يمسحه

اللوحة

الصلاحيات هي صلاحيات src/lib/roles.ts (لوحة الحجوزات)، والمضيف لا يصل إلا إلى إقاماته.

الطريقة والمسار الصلاحية ماذا تفعل
GET /api/dashboard/stats overview.view كل ما في النظرة العامة
GET /api/dashboard/calendar?from=&days= calendar.view الإقامات مقابل الليالي (62 يوماً كحد أقصى)، مع الحجز أو الإغلاق على كل ليلة محجوزة وسعر كل ليلة
POST /api/dashboard/blocks calendar.block {stayId, startDate, endDate, note}، وendDate صباح اليوم التالي لآخر ليلة مغلقة. يُرفض بـ 409 مع detail.nights إن كانت أي ليلة محجوزة
DELETE /api/dashboard/blocks/{id} calendar.block يفتح الليالي من جديد
GET /api/dashboard/bookings bookings.view المعاملات: status (أو CANCEL_REQUESTED)، وstayId، وq، وwhen (upcoming وpast وall)، وpage (‏50 في الصفحة)
POST /api/dashboard/bookings bookings.create حجز يدوي يتأكد فوراً: {stayId, checkIn, checkOut, guests, guestName, email, phone, country, notes, paid}
GET /api/dashboard/bookings/{id} bookings.view الحجز كاملاً بأسعار لياليه ورمز الباب والسجل
PATCH /api/dashboard/bookings/{id} حسب الحقل status (‏bookings.status، وCANCELLED يحتاج bookings.cancel)، وnote، وpaymentStatus (‏bookings.payment)، وinternalNote، وcancelRequested: false (‏bookings.cancel)
GET /api/dashboard/stays stays.view الإقامات (والمخفية أيضاً) بمضيفها وعدد حجوزاتها القادمة، وhosts للاختيار منهم
POST /api/dashboard/stays stays.edit إقامة جديدة
GET/PATCH/DELETE /api/dashboard/stays/{id} stays.view / stays.edit يغيّر PATCH الحقول المرسلة فقط، وseasons يستبدل كل المواسم. ولا يُسمح بـ DELETE إلا لإقامة بلا حجوزات
GET/POST /api/dashboard/destinations وPATCH/DELETE /api/dashboard/destinations/{id} stays.view / stays.edit الوجهات
GET /api/dashboard/inquiries?status= وPATCH .../{id} inquiries.manage {status: NEW, ANSWERED, CLOSED, note}
GET /api/dashboard/reviews?status=&stayId= وPATCH .../{id} reviews.reply {reply}، و{status: PUBLISHED, HIDDEN, PENDING} يحتاج reviews.moderate
POST /api/dashboard/ai/ask ai.use {question, history?, locale} ← {answer}
POST /api/dashboard/ai/describe stays.edit {nameAr, nameEn, type, destinationId, amenities, notes} ← {suggestion: {summaryAr, summaryEn, descAr, descEn}}
GET /api/dashboard/settings أي حساب مسجّل إعدادات الشركة، وهل مفاتيح ثواني مضبوطة
PATCH /api/dashboard/settings settings.edit تتغير الحقول المرسلة فقط
GET/POST /api/dashboard/admins وPATCH .../{id} admins.manage الحسابات: {name, role, active, password}
GET /api/dashboard/roles أي حساب مسجّل جدول الصلاحيات ودورك
POST /api/dashboard/upload stays.edit ملف file متعدد الأجزاء (JPEG أو PNG أو WebP حتى 4 ميغابايت) ← {url}

مثال: تأكيد حجز وتسجيل وصوله

curl -c jar -H "Content-Type: application/json" -d '{"email":"owner@nuzul.test","password":"..."}' http://localhost:3304/api/auth/login
curl -b jar -X PATCH -H "Content-Type: application/json" -d '{"status":"CONFIRMED"}' http://localhost:3304/api/dashboard/bookings/BOOKING_ID