إنتقل إلى المحتوى الرئيسي

واجهة برمجة تطبيقات التقويم وMCP

كل ما تفعله في imatic Calendar يمكنك أتمتته. استخدم REST API للاستعلام عن الأوقات وإنشاء الحجوزات، وخطافات الويب للتفاعل مع الأحداث في الزمن الحقيقي، وخادم MCP للسماح لوكيل ذكاء اصطناعي بالحجز نيابةً عنك. هذه الصفحة موجّهة للمطوّرين الذين يربطون imatic Calendar بتطبيقاتهم وأدواتهم الخاصة.

تدير بيانات الاعتماد ضمن للمطوّرين في لوحة التحكم.

تُدار من المسؤول

تُدار صفحتا مفاتيح API وخطافات الويب من مسؤول الحساب (مسؤول المؤسسة أو المسؤول الأعلى). إذا لم ترهما في لوحة التحكم، فاطلب من مسؤول على حسابك إصدار مفتاح أو إعداد خطاف ويب لك.

المصادقة ومفاتيح API​

تُصادَق الاستدعاءات إلى الواجهة باستخدام مفتاح API مُرسَل كرمز حامل (bearer token):

Authorization: Bearer <your_api_key>

أدِر المفاتيح ضمن للمطوّرين ← مفاتيح API، حيث يمكنك:

  • إنشاء مفتاح — انسخ السر عند عرضه؛ فهو لا يُعرض مرة أخرى.
  • سرد مفاتيحك ومعرفة الغرض من كل منها.
  • إبطال مفتاح فورًا إذا تسرّب أو لم يعد لازمًا.
  • تعيين نطاقات — يحمل كل مفتاح فقط الأذونات التي تمنحها، فمفتاح القراءة فقط يمكنه سرد الحجوزات لكن لا يمكنه أبدًا إنشاؤها أو إلغاؤها.

النطاقات المتاحة هي:

النطاقيمنح
slots:readقراءة الأوقات المتاحة لنوع فعالية
bookings:readسرد الحجوزات وقراءتها
bookings:writeإنشاء الحجوزات وإلغاؤها وإعادة جدولتها
mcpاستخدام خادم MCP (مظلّة تغطي أيضًا slots:read وbookings:read وbookings:write)
تعامل مع المفاتيح كأنها كلمات مرور

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

REST API الإصدار v1​

تُقدَّم REST API تحت المسار الأساسي /v1 وتُرجِع JSON. الموارد المتاحة هي:

  • أنواع الفعاليات — سرد وقراءة أنواع فعالياتك، إضافةً إلى تكرار نوع فعالية (POST /v1/event-types/:code/duplicate). (يتم الإنشاء والتعديل والحذف في لوحة التحكم.)
  • الأوقات — الاستعلام عن الأوقات المتاحة لنوع فعالية (الفرص نفسها المعروضة على صفحة الحجز، مع تطبيق كل الفواصل الزمنية والإشعار والحدود).
  • الحجوزات — CRUD كاملة إضافةً إلى إعادة الجدولة: إنشاء حجز، وسرد الحجوزات وقراءتها، والإلغاء، ونقل حجز إلى وقت جديد. يُرجِع GET /v1/bookings/stats عدد الحجوزات الإجمالي.
  • روابط الفعاليات — إنشاء وسرد وإبطال روابط حجز ذات استخدام واحد مرتبطة بنوع فعالية (POST/GET /v1/event-types/:code/links وDELETE /v1/event-links/:linkCode).
  • خطافات الويب — أدِر اشتراكات خطافات الويب برمجيًا.
  • المستخدمون / أنا — يُرجِع GET /v1/users/me هوية مفتاح API (الحساب والمؤسسة المُصادَق عليهما).
  • التقويمات — اعمل مع تقويماتك المتصلة (انظر التكاملات).

مسار أتمتة نموذجي: استعلم عن الأوقات لنوع فعالية، ثم أنشئ حجزًا للوقت الذي اختاره مستخدمك — يسري على الواجهة أيضًا ضمان الذرّية وعدم الحجز المزدوج نفسه الذي تستخدمه صفحة الحجز.

خطافات الويب​

تدفع خطافات الويب الأحداث إلى خادمك لحظة حدوثها، فلا تحتاج إلى الاستقصاء. أدِرها ضمن للمطوّرين ← خطافات الويب.

  • اشترك برابط لتلقّي أحداث الحجز. الأحداث هي بالضبط: booking.created وbooking.cancelled وbooking.rescheduled وbooking.no_show.
  • كل عملية تسليم موقّعة بـ HMAC — تحقّق من ترويسة التوقيع مقابل سرّ خطاف الويب الخاص بك لتأكيد أن الطلب جاء فعلًا من imatic Calendar قبل أن تثق بالحمولة.
  • استخدم إجراء الاختبار المدمج لإرسال حدث عيّنة إلى نقطة النهاية لديك أثناء البناء، حتى تتمكن من تأكيد أن معالجك يعمل قبل الإطلاق.

يسري التوقيع في الترويسة X-Imatic-Signature، بتنسيق على نمط Stripe:

X-Imatic-Signature: t=<unix-epoch-seconds>,v1=<hmac-sha256>

للتحقق: خذ t وجسم الطلب الخام، واحسب HMAC-SHA256(secret, "<t>.<body>") (الطابع الزمني والجسم موصولين بنقطة حرفية)، ورمّزه بالنظام الست عشري، وقارنه بـ v1. ارفض الطلب إذا لم يتطابقا.

تحقّق دائمًا من التوقيع

ارفض أي خطاف ويب لا يتطابق توقيع HMAC الخاص به. هذا هو الفرق بين أتمتة جديرة بالثقة وباب مفتوح.

خادم MCP​

يأتي imatic Calendar مزوّدًا بـخادم بروتوكول سياق النموذج (MCP)، حتى يتمكن وكلاء الذكاء الاصطناعي والمساعدون من قراءة توافرك وإدارة الحجوزات عبر أدوات محددة جيدًا — باستخدام مصادقة مفتاح API والنطاقات نفسها التي تستخدمها REST API.

يكشف الخادم عن سبع أدوات:

الأداةما تفعله
list_event_typesسرد أنواع فعالياتك القابلة للحجز
list_slotsالحصول على الأوقات المتاحة لنوع فعالية
create_bookingحجز وقت
cancel_bookingإلغاء حجز
reschedule_bookingنقل حجز إلى وقت جديد
list_bookingsسرد الحجوزات الموجودة
get_bookingقراءة حجز واحد برمزه

وجّه عميلك القادر على MCP إلى الخادم، وصادِق بمفتاح API، وسيتمكن وكيلك من الإجابة عن "متى تكون Priya متفرغة يوم الخميس؟" وحجز الوقت — كل ذلك ضمن النطاقات التي منحتها لذلك المفتاح.

تُقرأ بيانات الملف الشخصي الخاصة بالحساب عبر REST باستخدام GET /v1/users/me، وليس عبر أداة MCP.

قيّد نطاق مفتاح وكيلك بإحكام

امنح وكيل الذكاء الاصطناعي مفتاحًا يحمل فقط الأدوات التي يحتاجها. إذا كان يحتاج فقط إلى قراءة التوافر، فلا تمنحه أذونات الإلغاء أو إعادة الجدولة.

الخطوات التالية​