كل النقاط تستقبل 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