قراءة حجز واحد بمعرّفه، الطلب GET /api/v1/bookings/{id}

قراءة حجز واحد تتم بالطلب GET /api/v1/bookings/{id}، حيث {id} معرّف الحجز من قائمة الحجوزات. يعيد الطلب الحجز بحالته الحالية وبالحقول نفسها التي في القائمة، ويحتاج إلى مفتاح بصلاحية bookings.read.

متى أستخدم قراءة حجز واحد؟

استخدمها عندما يكون معك معرّف حجز وتريد حالته الآن.

• بعد حدث Webhook: يصلك حدث حجز جديد أو ملغى، فتقرأ الحجز بمعرّفه لتتأكد من حالته قبل أن تبني عليه. انظر Webhooks.
• لمتابعة حجز بعينه: لتعرف هل صار «حضر» أو «لم يحضر» بعد موعده.

ما المعاملات التي يأخذها الطلب؟

يأخذ معاملًا واحدًا في المسار:

المعامل	المكان	معناه
id	المسار	معرّف الحجز كما جاء في id بقائمة الحجوزات

المعرّف بصيغة غير صحيحة يعود بالخطأ 404، تمامًا كالمعرّف غير الموجود.

كيف أرسل الطلب؟

curl https://api.mujib.ai/api/v1/bookings/3f0c9a52-7d1e-4b8a-9c41-2e6f8a1b0d77 \
  -H "Authorization: Bearer $MUJIB_API_KEY"

const id = '3f0c9a52-7d1e-4b8a-9c41-2e6f8a1b0d77';
const res = await fetch(`https://api.mujib.ai/api/v1/bookings/${encodeURIComponent(id)}`, {
  headers: { Authorization: `Bearer ${process.env.MUJIB_API_KEY}` },
});
const body = await res.json();
if (res.status === 404) console.log('not in this business');
else if (!res.ok) throw new Error(`${res.status} ${body.error.code}: ${body.error.message}`);
else console.log(body.data.status, body.data.localTime, body.data.timezone);

import os
import requests

booking_id = "3f0c9a52-7d1e-4b8a-9c41-2e6f8a1b0d77"
res = requests.get(
    f"https://api.mujib.ai/api/v1/bookings/{booking_id}",
    headers={"Authorization": f"Bearer {os.environ['MUJIB_API_KEY']}"},
    timeout=30,
)
body = res.json()
if res.status_code == 404:
    print("not in this business")
elif not res.ok:
    raise RuntimeError(f"{res.status_code} {body['error']['code']}: {body['error']['message']}")
else:
    print(body["data"]["status"], body["data"]["localTime"], body["data"]["timezone"])

كيف يبدو الرد؟

رد ناجح بالرمز 200، والحجز في data. البيانات مثال مختلَق:

{
  "data": {
    "id": "3f0c9a52-7d1e-4b8a-9c41-2e6f8a1b0d77",
    "status": "confirmed",
    "source": "agent",
    "service": "consultation",
    "startsAt": "2026-11-12T07:30:00Z",
    "localTime": "2026-11-12T10:30:00",
    "timezone": "Asia/Amman",
    "durationMinutes": 30,
    "branch": { "id": "e7f6a5b4-3c2d-4e1f-9a8b-7c6d5e4f3a21", "name": "الفرع الرئيسي" },
    "specialist": "ليلى",
    "customer": { "contactId": "5d8f2a61-0c4e-4b7a-9f13-6e2b8c0d4a57", "name": "سارة", "phone": "962790000000" },
    "createdAt": "2026-11-04T18:22:09.117Z"
  }
}

معنى كل حقل وقيم status وsource في قائمة الحجوزات. وإذا كان customer.contactId معرّفًا لا null، فاقرأ به العميل في قراءة عميل واحد.

ماذا يعني الخطأ 404 هنا؟

يعني أن واجهة نشاطك لا تعرف حجزًا بهذا المعرّف:

{ "error": { "code": "NOT_FOUND", "message": "Booking not found" } }

يعود الخطأ نفسه للمعرّف غير الموجود، وللمعرّف الذي يتبع نشاطًا آخر، وللمعرّف بصيغة غير صحيحة، وللسجل التاريخي المستورد من سجل قديم، وهو السجل الذي لا يظهر في القائمة أيضًا. وباقي الأخطاء:

HTTP	code	السبب
401	UNAUTHORIZED	لا مفتاح، أو مفتاح غير صالح
403	FORBIDDEN	المفتاح لا يحمل bookings.read
429	RATE_LIMITED	تجاوزت حدود الطلبات
500	INTERNAL	خطأ غير متوقع في الخادم

الأسئلة الشائعة

من أين أحصل على معرّف الحجز؟

من الحقل id في قائمة الحجوزات، أو من حدث الحجز الذي يصلك عبر Webhooks.

هل أستطيع تعديل الحجز أو إلغاءه بهذا الطلب؟

لا. الواجهة للقراءة فقط. التعديل والإلغاء من تقويم لوحة التحكم.

لماذا يعود الخطأ 404 لحجز أراه في لوحة التحكم؟

إذا كان من السجلات التاريخية المستوردة من سجل قديم، فهو ليس جزءًا من الواجهة. وإلا فتحقق أن المفتاح من النشاط نفسه وأن المعرّف كامل.

صفحات ذات صلة

• قائمة الحجوزات عبر API بالطلب GET /api/v1/bookings
• قراءة عميل واحد بمعرّفه، الطلب GET /api/v1/contacts/{id}
• Webhook واتساب: استقبال أحداث واتساب وإنستغرام وماسنجر