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

> قراءة حجز واحد عبر واجهة مُجيب البرمجية بمعرّفه، بطلب GET /api/v1/bookings/{id}، لتعرف حالته الآن، مع أمثلة بـ curl وJavaScript وPython وشكل الرد والأخطاء.

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

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

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

- **بعد حدث Webhook:** يصلك حدث حجز جديد أو ملغى، فتقرأ الحجز بمعرّفه لتتأكد من حالته قبل أن تبني عليه. انظر [Webhooks](https://docs.mujib.ai/developers/webhooks/).
- **لمتابعة حجز بعينه:** لتعرف هل صار «حضر» أو «لم يحضر» بعد موعده.

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

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

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

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

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

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

```js
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);
```

```python
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`. البيانات مثال مختلَق:

```json
{
  "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` في [قائمة الحجوزات](https://docs.mujib.ai/developers/api-bookings/). وإذا كان `customer.contactId` معرّفًا لا `null`، فاقرأ به العميل في [قراءة عميل واحد](https://docs.mujib.ai/developers/api-contact/).

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

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

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

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

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

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

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

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

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

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

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

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

---

المصدر: https://docs.mujib.ai/developers/api-booking/ · آخر تحديث: 2026-11-04