قائمة الحجوزات عبر API بالطلب GET /api/v1/bookings

قائمة الحجوزات عبر API يعيدها الطلب GET /api/v1/bookings: مواعيد نشاطك بترتيبها الزمني، مع وقت كل موعد المحلي في فرعه ولحظته بتوقيت UTC، وتختارها بالأيام وبالحالة. يحتاج الطلب إلى مفتاح بصلاحية bookings.read.

ما الذي يعيده طلب قائمة الحجوزات؟

يعيد الطلب صفحة من الحجوزات في data، من الأقدم موعدًا إلى الأحدث، ومعها nextCursor للصفحة التالية، أو null إذا كانت هذه آخر صفحة.

إذا لم ترسل from ولا to، فتأتي كل الحجوزات من أقدمها، الماضية والقادمة.
تظهر المواعيد التي حجزها الوكيل أو فريقك في مُجيب. أما السجلات التاريخية المستوردة من سجل قديم فليست جزءًا من الواجهة.
يظهر خيار «قراءة الحجوزات» عند إنشاء المفتاح فقط إذا كان نشاطك يستخدم المواعيد.

ما المعاملات التي يقبلها الطلب؟

كل المعاملات اختيارية، وأي معامل غيرها يعود بالخطأ 400:

المعامل	النوع	معناه
`from`	تاريخ `YYYY-MM-DD`	أول يوم، ويدخل في النتائج
`to`	تاريخ `YYYY-MM-DD`	آخر يوم، ويدخل في النتائج
`status`	نص	حالة واحدة فقط (انظر الجدول التالي)
`limit`	عدد صحيح	عدد الحجوزات في الصفحة، 50 إذا لم ترسله وحتى 100
`cursor`	نص	`nextCursor` من الصفحة السابقة. انظر التقسيم إلى صفحات

from وto أيام بتقويم كل فرع وبمنطقته الزمنية، لا بتوقيت UTC. حجز الساعة العاشرة صباحًا في فرعك يقع في يومه كما تراه في لوحة التحكم.
يجب أن يكون التاريخ يومًا حقيقيًا: 2026-02-31 يُرفض بالخطأ 400، وكذلك أن يقع from بعد to.
لحجوزات يوم واحد اجعل from وto اليوم نفسه.

قيم status، وما يقابلها في تقويم لوحة التحكم:

القيمة	في لوحة التحكم
`requested`	«قيد الانتظار»
`confirmed`	«مؤكّد»
`cancelled`	«ملغى»
`completed`	«حضر»
`no_show`	«لم يحضر»

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

هذا المثال يطلب الحجوزات المؤكدة في شهر كامل:

curl "https://api.mujib.ai/api/v1/bookings?from=2026-11-01&to=2026-11-30&status=confirmed&limit=100" \
  -H "Authorization: Bearer $MUJIB_API_KEY"

const url = new URL('https://api.mujib.ai/api/v1/bookings');
url.searchParams.set('from', '2026-11-01');
url.searchParams.set('to', '2026-11-30');
url.searchParams.set('status', 'confirmed');
url.searchParams.set('limit', '100');

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.MUJIB_API_KEY}` },
});
const body = await res.json();
if (!res.ok) throw new Error(`${res.status} ${body.error.code}: ${body.error.message}`);
for (const b of body.data) console.log(b.localTime, b.branch?.name, b.customer.name);

import os
import requests

res = requests.get(
    "https://api.mujib.ai/api/v1/bookings",
    params={"from": "2026-11-01", "to": "2026-11-30", "status": "confirmed", "limit": 100},
    headers={"Authorization": f"Bearer {os.environ['MUJIB_API_KEY']}"},
    timeout=30,
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {body['error']['code']}: {body['error']['message']}")
for b in body["data"]:
    print(b["localTime"], (b["branch"] or {}).get("name"), b["customer"]["name"])

لقراءة كل الصفحات حتى النهاية، استخدم الدالة في التقسيم إلى صفحات.

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

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

{
  "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"
    },
    {
      "id": "c2a7e915-6f3b-4d80-b4e1-7a9d5c0f2b36",
      "status": "requested",
      "source": "staff",
      "service": "followup",
      "startsAt": "2026-11-12T09:00:00Z",
      "localTime": "2026-11-12T12:00:00",
      "timezone": "Asia/Amman",
      "durationMinutes": null,
      "branch": { "id": "e7f6a5b4-3c2d-4e1f-9a8b-7c6d5e4f3a21", "name": "الفرع الرئيسي" },
      "specialist": null,
      "customer": { "contactId": null, "name": "أحمد", "phone": "0790000000" },
      "createdAt": "2026-11-05T08:01:44.360Z"
    }
  ],
  "nextCursor": "MjAyNi0xMS0xMlQxMjowMDowMHxjMmE3ZTkxNS02ZjNiLTRkODAtYjRlMS03YTlkNWMwZjJiMzY"
}

كل حجز فيه هذه الحقول دائمًا، والحقل الذي لا قيمة له يأتي null:

الحقل	النوع	معناه
`id`	نص	معرّف الحجز الثابت، تستخدمه في قراءة حجز واحد
`status`	نص	حالة الحجز (انظر الجدول السابق)
`source`	نص	من أنشأ الحجز: `agent` الوكيل في محادثة، أو `staff` فريقك من لوحة التحكم
`service`	نص	معرّف نوع الزيارة كما عرّفه نشاطك، مثل `consultation`، لا اسمه المعروض. انظر أنواع الزيارات
`startsAt`	لحظة UTC	بداية الموعد بتوقيت UTC، بالصيغة `YYYY-MM-DDTHH:MM:SSZ`
`localTime`	نص	بداية الموعد بساعة الفرع، دون فرق توقيت، بالصيغة `YYYY-MM-DDTHH:MM:SS`. هذا هو الوقت الذي أُعطي للعميل
`timezone`	نص	المنطقة الزمنية لـ `localTime`، مثل `Asia/Amman`: منطقة الفرع، وإلا منطقة نشاطك
`durationMinutes`	عدد صحيح أو `null`	مدة الموعد بالدقائق، أو `null` إذا انطبقت المدة الافتراضية لنشاطك
`branch`	كائن أو `null`	الفرع بالحقلين `id` و`name`، أو `null` إذا لم يكن للحجز فرع
`specialist`	نص أو `null`	اسم الأخصائي، أو `null` إذا لم يُحدَّد
`customer.contactId`	نص أو `null`	معرّف العميل لـ قراءة عميل واحد، أو `null` لحجز بلا عميل مسجّل
`customer.name`	نص أو `null`	الاسم المكتوب على الحجز، وإلا اسم العميل
`customer.phone`	نص أو `null`	الرقم المكتوب على الحجز، وإلا رقم العميل
`createdAt`	لحظة UTC	متى أُنشئ الحجز

ما الأخطاء المحتملة؟

HTTP	`code`	السبب
400	`VALIDATION_ERROR`	معامل غير معروف، أو تاريخ بغير الصيغة `YYYY-MM-DD` أو ليس يومًا حقيقيًا، أو `from` بعد `to`، أو `status` غير معروف، أو `limit` خارج المسموح، أو مؤشر لا يُقرأ
401	`UNAUTHORIZED`	لا مفتاح، أو مفتاح غير صالح
403	`FORBIDDEN`	المفتاح لا يحمل `bookings.read`
429	`RATE_LIMITED`	تجاوزت حدود الطلبات
500	`INTERNAL`	خطأ غير متوقع في الخادم

التفاصيل في الأخطاء وحدود الطلبات.

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

هل from وto بتوقيت UTC؟

لا. هما أيام بتقويم كل فرع وبمنطقته الزمنية، ويشملان اليومين نفسيهما. أما startsAt في الرد فلحظة بتوقيت UTC.

هل تظهر الحجوزات القديمة التي استوردتها من سجل سابق؟

لا. السجلات التاريخية المستوردة من سجل قديم ليست جزءًا من الواجهة. تظهر المواعيد المحجوزة في مُجيب.

ماذا يعني durationMinutes بقيمة null؟

أن الحجز لا يحمل مدة خاصة به، فتنطبق عليه المدة الافتراضية التي ضبطها نشاطك.

هل أعرف من القائمة الحجوزات التي تغيّرت حديثًا؟

لا يوجد معامل لذلك. اقرأ نافذة الأيام التي تهمك من جديد، أو استخدم Webhooks ليصلك كل حجز جديد أو ملغى لحظة حدوثه.

مُجيب منتج شركة المجيب الذكي لتكنولوجيا المعلومات (ذات مسؤولية محدودة)، عمّان، الأردن. رقم التسجيل82888.

الخصوصية الشروط تواصل معنا llms.txt