الحجز عبر Cal.com

ربط التقويم#

افتح الوكيل ← الإجراءات ← Cal.com. أدخل مفتاح Cal.com API يبدأ بـ cal_، ومعرّف نوع الحدث الرقمي الموجب، ومنطقة زمنية بصيغة IANA مثل Asia/Seoul. ثم اختر حفظ الاتصال. لكل وكيل اتصاله الخاص. يُشفَّر المفتاح على الخادم، ولا تعرض لوحة التحكم سوى آخر أربعة أحرف منه. اترك حقل المفتاح فارغًا عند تحديث اتصال قائم للإبقاء على المفتاح الحالي.

اختر اختبار الاتصال لقراءة ما يصل إلى ثلاثة أوقات متاحة قادمة خلال الأيام السبعة التالية باستخدام الإعدادات المُدخلة. لا يحفظ هذا الاختبار الاتصال ولا ينشئ حجزًا. قد يعني غياب الأوقات ببساطة أن نوع الحدث لا يتوفر له أي وقت متاح في هذه الفترة. إذا فشل الاختبار، فتحقق من المفتاح ونوع الحدث والجدول الزمني في Cal.com. يؤدي حذف الاتصال إلى إيقاف حجوزات Cal.com الجديدة، لكنه لا يلغي الحجوزات الموجودة.

المدفوعات خارج النطاق. يمثّل Google Calendar خيارًا منفصلًا غير متاح للجميع بعد.

من الأوقات المتاحة إلى الحجز#

1. يستدعي الوكيل find_slots للحصول على الأوقات المستقبلية المتاحة فعلًا. يعرض ما يصل إلى ثمانية أوقات بالمنطقة الزمنية المضبوطة. النطاق الافتراضي من اليوم حتى بعد سبعة أيام، والحد الأقصى لمدى التواريخ هو 14 يومًا. إذا كان هناك وقت متاح واحد فقط، يُعرض وحده.
2. يختار العميل وقتًا ويزوّد الوكيل باسمه وبريده الإلكتروني وملاحظة اختيارية. يتحقق الوكيل مجددًا من أن الوقت ما زال متاحًا وأنه عُرض في هذه المحادثة. تنتهي صلاحية عروض الأوقات بعد 15 دقيقة.
3. تعرض بطاقة التأكيد التاريخ والوقت والمنطقة الزمنية وبيانات الحاضر. يجب على العميل الضغط على تأكيد. لا يؤدي إرسال رسالة في المحادثة أو اختيار وقت وحده إلى إجراء أي حجز. تنتهي صلاحية الاقتراح بعد 15 دقيقة، ولا يحجز الوقت.
4. بعد التأكيد فقط يرسل المحوّل طلب الحجز إلى Cal.com. تتحول النتيجة accepted من Cal.com إلى done، مع معرّف UID للحجز كمرجع. أما pending أو awaiting_host فتبقى قيد الانتظار، ويتحول الرفض أو الإلغاء إلى حالة فشل.

لا تُتاح اقتراحات الحجز على قنوات المراسلة إلا في المحادثات الخاصة. لا تستدعي المحاكاة Cal.com ولا تنشئ حجزًا. وبدون اتصال Cal.com يظل مسار طلب الحجز الحالي متاحًا، لكنه لا يثبت وجود حجز فعلي في التقويم. يؤدي تغيير المفتاح أو نوع الحدث أو المنطقة الزمنية إلى إبطال هدف تنفيذ الاقتراح، لذا ابدأ من جديد بعد أي تغيير في الاتصال.

إذا أُخذ الوقت أو كانت النتيجة غير مؤكدة#

قد يحجز عميل آخر الوقت قبل اكتمال التأكيد. إذا لم يعد الوقت متاحًا، يُبلغ الوكيل بعدم توفره، وإذا رفضه Cal.com أثناء الإنشاء، يعرض الإيصال حالة الفشل. اطلب أوقاتًا جديدة وأكّد اقتراحًا جديدًا. لا يرفق إيصال الفشل خيارات جديدة تلقائيًا.

انتهاء مهلة الشبكة ليس دليلًا على الفشل ولا على النجاح. يعرض الإيصال نتيجة غير معروفة بينما تعيد الخدمة الفحص. لا تحتوي نقطة إنشاء الحجز في Cal.com على عقد موثّق لمفتاح عدم التكرار (idempotency key)، لذا يخزّن المحوّل معرّف التشغيل في metadata.maf_run ويبحث عن ذلك الحجز في جميع الحالات والصفحات قبل إعادة محاولة الإنشاء. ولا يسمح بحث غير مكتمل أبدًا بإرسال طلب إنشاء آخر. يقلل هذا خطر التكرار، لكنه ليس ضمانًا بالتنفيذ مرة واحدة بالضبط مدعومًا من المزوّد. وقبل إجراء حجز آخر بعد استنفاد المحاولات، تحقق من Cal.com.

تختلف موافقة المضيف في Cal.com عن موافقة المالك على إجراءات التغيير المخصصة. لا يحدّث هذا التكامل حجز Cal.com المعلّق تلقائيًا، فتحقق من حالته النهائية في Cal.com. يمكن لأداة الويب استطلاع إيصال التشغيل المخزّن، وتتلقى القنوات الخاصة المدعومة إيصالات متأخرة وفق نوافذ الخدمة الخاصة بها. راجع تسليم الإيصالات.

إصدارات API وفحوصات الإطلاق#

يرسل المحوّل مصادقة Bearer وقيم cal-api-version التالية الخاصة بكل نقطة نهاية، وقد جرى التحقق منها مقابل الوثائق الرسمية بتاريخ 2026-10-13:

قبل استخدامه مع العملاء، اختبر حجزًا مُتحكَّمًا به، وتحقق من UID في Cal.com، وجرّب وقتًا محجوزًا، وافحص الإيصالات على كل قناة تنوي استخدامها. لا يثبت نجاح اختبار الاتصال سوى قراءة الأوقات المتاحة، وليس حجزًا فعليًا ولا جاهزية للإنتاج.