> ## Documentation Index > Fetch the complete documentation index at: https://developers.huechat.ai/llms.txt > Use this file to discover all available pages before exploring further. # المواعيد والجدولة > ضبط أنواع المواعيد والموارد والتوفر، والبحث عن الأوقات، ومزامنة دورة الحجز كاملة عبر 30 عملية API معزولة لكل حساب. واجهة المواعيد هي واجهة الجدولة بين الأنظمة في HueChat. يستطيع نظام ERP أو CRM أو موقع أو تطبيق أو منصة شريكة ضبط دليل الحجز، والبحث عن الأوقات المتاحة، وإنشاء مواعيد العملاء وإدارة دورتها كاملة. يُحصر كل طلب في الحساب الذي أصدر مفتاح API. ## قبل البدء أنشئ [مفتاح API محدود النطاق](/ar/api-keys) بأقل الصلاحيات اللازمة: | النطاق | استخدامه | | ----------------------- | ------------------------------------------------------------------------------- | | `appointments:read` | قراءة المواعيد والدليل والإعدادات والموارد والخدمات والتوفر والأوقات والتقارير | | `appointments:write` | إنشاء الموعد وتعديله وإعادة جدولته وتغيير حالته | | `appointments:settings` | ضبط الإعدادات والموارد والخدمات والتوفر؛ يجب أن يكون مالك المفتاح مديرًا للحساب | | `contacts:read` | التحقق من `contact_id` المرسل | | `contacts:write` | إنشاء جهة الاتصال أو مزامنتها أولًا عبر واجهة جهات الاتصال | | `deals:write` | إنشاء موعد مرتبط بـ`deal_id` أو تغييره | | `deals:read` | إظهار بيانات الصفقة المرتبطة في تفاصيل الموعد | استخدم معرّف الحساب الذي أصدر المفتاح. يُرفض مفتاح حساب آخر بالرمز `403`، ولا تُحل معرّفات الموارد أو الخدمات أو المواعيد أو جهات الاتصال أو الصفقات بين الحسابات. كما تتحقق عمليات الإعداد من أن مالك المفتاح ما زال مديرًا. يجب أن تكون ميزة المواعيد الأصلية مفعلة في الحساب. يعيد عدم توفر الميزة في الخطة الرمز `402` من دون تجاوز بقية فحوص الصلاحيات. ## التغطية الكاملة للواجهة يتضمن العقد العام 30 عملية. يُسمى نوع الموعد **خدمة** في حقول API، ويمكن أن يمثل المورد طبيبًا أو موظفًا أو غرفة أو فرعًا أو جهازًا أو أي سعة قابلة للحجز. ### القراءة والبحث والحجز | الطريقة | المسار | النطاق | المعنى | | ------- | -------------------------------------- | -------------------- | ------------------------------------------------------------- | | `GET` | `/appointments` | `appointments:read` | قراءة المواعيد وسياق الجدولة ضمن مدة RFC3339 | | `GET` | `/appointments/{id}` | `appointments:read` | قراءة موعد وسجل حالته والصفقة المرتبطة المسموح بها | | `GET` | `/appointments/external/{externalId}` | `appointments:read` | إيجاد الموعد بالمعرّف الثابت في النظام الخارجي | | `GET` | `/appointments/catalog` | `appointments:read` | قراءة الخدمات النشطة والموارد المؤهلة لكل خدمة | | `GET` | `/appointments/settings` | `appointments:read` | قراءة المنطقة الزمنية وفاصل الأوقات وأفق الحجز وسياسة التأكيد | | `GET` | `/appointments/resources` | `appointments:read` | عرض الموارد النشطة والمؤرشفة | | `GET` | `/appointments/resources/{resourceId}` | `appointments:read` | قراءة مورد واحد | | `GET` | `/appointments/services` | `appointments:read` | عرض أنواع المواعيد النشطة والمؤرشفة | | `GET` | `/appointments/services/{serviceId}` | `appointments:read` | قراءة نوع موعد واحد | | `GET` | `/appointments/availability` | `appointments:read` | قراءة قواعد الأسبوع واستثناءات الفتح والإغلاق | | `GET` | `/appointments/slots` | `appointments:read` | إيجاد أوقات قابلة للحجز حسب الخدمة والمورد الاختياري | | `GET` | `/appointments/reports` | `appointments:read` | قراءة إجماليات الحالات والأداء حسب الخدمة | | `POST` | `/appointments` | `appointments:write` | إنشاء موعد خارجي أو إعادة الطلب نفسه بأمان | | `PATCH` | `/appointments/{id}` | `appointments:write` | تعديل بيانات العميل، وللموعد النشط خدمته أو مورده أو وقته | | `PATCH` | `/appointments/{id}/status` | `appointments:write` | تغيير الحالة بين مبدئي ومحجوز ومؤكد ومكتمل وملغي وعدم حضور | | `PATCH` | `/appointments/{id}/schedule` | `appointments:write` | نقل موعد نشط إلى وقت متاح | ### إعدادات المدير تتطلب كل عملية في هذا الجدول `appointments:settings` وأن يكون مالك المفتاح مديرًا للحساب. | الطريقة | المسار | المعنى | | -------- | ----------------------------------------------------- | ------------------------------------------- | | `PUT` | `/appointments/settings` | إنشاء سياسة الجدولة الأصلية أو تحديثها | | `POST` | `/appointments/resources` | إنشاء طبيب أو غرفة أو فرع أو مورد آخر | | `PUT` | `/appointments/resources/{resourceId}` | تحديث مورد | | `DELETE` | `/appointments/resources/{resourceId}` | أرشفة المورد مع الاحتفاظ بتاريخ المواعيد | | `POST` | `/appointments/resources/{resourceId}/restore` | استعادة مورد مؤرشف | | `POST` | `/appointments/services` | إنشاء نوع موعد بمدة وفواصل وسعر اختياري | | `PUT` | `/appointments/services/{serviceId}` | تحديث نوع موعد | | `DELETE` | `/appointments/services/{serviceId}` | أرشفة خدمة مع الاحتفاظ بتاريخ المواعيد | | `POST` | `/appointments/services/{serviceId}/restore` | استعادة خدمة مؤرشفة | | `PUT` | `/appointments/services/{serviceId}/resources` | استبدال قائمة الموارد المؤهلة للخدمة | | `POST` | `/appointments/availability/rules` | استبدال قاعدة يوم واحد لمورد واحد | | `POST` | `/appointments/availability/rules/bulk` | استبدال ما يصل إلى سبع قواعد أسبوعية ذرّيًا | | `POST` | `/appointments/availability/exceptions` | إضافة فترة فتح أو إغلاق استثنائية | | `DELETE` | `/appointments/availability/exceptions/{exceptionId}` | حذف استثناء توفر | جميع المسارات أعلاه تضاف إلى `/api/v2/accounts/{accountId}`. ## شرح عمليات القراءة واحدةً واحدة * `GET /appointments`: يعيد مواعيد النطاق مع الموارد والخدمات والإعدادات والقواعد والاستثناءات وروابط الخدمة بالموارد. النطاق الافتراضي 14 يومًا، ويمكن إرسال `start` و`end` بصيغة RFC3339 حتى 366 يومًا. * `GET /appointments/{id}`: يقبل `public_id` أو UUID، ويعيد الموعد وسجل تغير الحالة. لا تظهر الصفقة المرتبطة إلا مع `deals:read`. * `GET /appointments/external/{externalId}`: الأنسب للمطابقة بعد إعادة محاولة أو عندما لا يخزن النظام الخارجي معرّف HueChat. * `GET /appointments/catalog`: يعيد الخدمات النشطة فقط، ومدة كل خدمة وفواصلها والموارد المسموح لها تقديمها؛ وهو أفضل طلب لواجهة حجز خارجية. * `GET /appointments/settings`: يبين المنطقة الزمنية وفاصل الأوقات وأقل مهلة وأقصى مدة للحجز وسياسة التأكيد من دون تغييرها. * `GET /appointments/resources` و`GET /appointments/resources/{resourceId}`: يعيدان بيانات الأشخاص والغرف والفروع والأجهزة، بما في ذلك النوع والمنطقة الزمنية واللون والترتيب والحالة النشطة. * `GET /appointments/services` و`GET /appointments/services/{serviceId}`: يعيدان أنواع الموعد مع المدة وفواصل ما قبل/بعد الموعد والسعر والعملة والحالة. * `GET /appointments/availability`: يعيد قواعد الأسبوع كلها والاستثناءات التي تتقاطع مع `start` و`end`. المدة القصوى 366 يومًا. * `GET /appointments/slots`: يتطلب `date` وخدمة بالمعرّف أو الاسم الدقيق، ويقبل موردًا اختياريًا و`preferred_time` و`limit` حتى 50. يعيد وقت البداية والنهاية بصيغة مطلقة ومحلية لكل مورد متاح. * `GET /appointments/reports`: يعيد إجماليات الحالات والحجوزات المنشأة بالذكاء الاصطناعي وتوزيع النتائج حسب الخدمة. المدة الافتراضية شهر وأقصاها 366 يومًا. ## شرح عمليات الكتابة واحدةً واحدة * `POST /appointments`: ينشئ حجزًا من `external_id` وبيانات العميل والخدمة والوقت. يقبل UUID أو اسم الخدمة الدقيق، وموردًا اختياريًا بالـUUID أو الاسم، و`starts_at` أو `date` مع `time`. إعادة الطلب نفسه لا تنشئ نسخة ثانية. * `PATCH /appointments/{id}`: يحدّث بيانات العميل القابلة للتحرير، ويمكنه نقل موعد نشط في العملية نفسها. أرسل المورد والخدمة ووقت البداية وحقول العميل و`version` الحالي. * `PATCH /appointments/{id}/status`: يغير الحالة مع `reason` اختياري ونسخة متوقعة. يحفظ التغيير وسجل الحالة في معاملة واحدة. * `PATCH /appointments/{id}/schedule`: ينقل موعدًا مبدئيًا أو محجوزًا أو مؤكدًا إلى مورد وخدمة ووقت متاح، ويرفض النسخة القديمة أو التعارض. ## شرح عمليات الإعداد واحدةً واحدة * `PUT /appointments/settings`: يحفظ الوضع والمنطقة الزمنية وفاصل الأوقات ومهل الحجز والإلغاء وبداية الأسبوع والعرض وسياسة التأكيد كإعداد متماسك. * `POST /appointments/resources`: ينشئ سعة قابلة للحجز باسم ونوع، مع وصف ومنطقة زمنية ولون وترتيب اختياري. * `PUT /appointments/resources/{resourceId}`: يغير الحقول المرسلة فقط، ويمكنه تفعيل المورد أو تعطيله. * `DELETE /appointments/resources/{resourceId}`: أرشفة آمنة؛ تختفي السعة من الحجوزات الجديدة لكن لا يحذف تاريخها. * `POST /appointments/resources/{resourceId}/restore`: يعيد المورد المؤرشف ليصبح متاحًا للإعداد والحجز. * `POST /appointments/services`: ينشئ نوع الموعد باسمه ومدته بين 5 و1440 دقيقة وفواصله وسعره وعملته. * `PUT /appointments/services/{serviceId}`: يغير الحقول المرسلة فقط، بما فيها المدة والسعر والترتيب والحالة النشطة. * `DELETE /appointments/services/{serviceId}`: يؤرشف النوع مع إبقاء المواعيد السابقة قابلة للقراءة. * `POST /appointments/services/{serviceId}/restore`: يعيد نوع الموعد المؤرشف. * `PUT /appointments/services/{serviceId}/resources`: يستبدل جميع تعيينات الخدمة بقائمة UUID المرسلة؛ القائمة الفارغة تعني كل الموارد النشطة. * `POST /appointments/availability/rules`: يستبدل قاعدة مورد/يوم واحدة. يستخدم `day_of_week` القيم 0–6 والدقائق منذ منتصف الليل. * `POST /appointments/availability/rules/bulk`: يتحقق من جميع القواعد أولًا ثم يحفظها معًا، ولذلك لا يترك جدولًا نصف محدث. * `POST /appointments/availability/exceptions`: ينشئ فترة `open` أو `closed`؛ حذف `resource_id` يجعلها عامة لكل الموارد. * `DELETE /appointments/availability/exceptions/{exceptionId}`: يحذف الاستثناء المحدد داخل الحساب ولا يمس سجل المواعيد. ## ضبط نموذج الجدولة ### 1. حفظ إعدادات الحساب تُستخدم منطقة IANA الزمنية عند إرسال `date` و`time` محليين. ```bash theme={null} curl -X PUT "https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/appointments/settings" \ -H "Authorization: Bearer $HUECHAT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "native_enabled": true, "booking_mode": "native", "timezone": "Asia/Riyadh", "slot_interval_minutes": 15, "minimum_notice_minutes": 60, "maximum_advance_days": 90, "cancellation_notice_minutes": 120, "week_starts_on": 0, "default_view": "week", "resource_label": "Doctor", "confirmation_mode": "automatic" }' ``` ### 2. إنشاء مورد ونوع موعد ```bash theme={null} curl -X POST "https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/appointments/resources" \ -H "Authorization: Bearer $HUECHAT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "د. سارة", "resource_type": "Doctor", "description": "استشارية جلدية", "timezone": "Asia/Riyadh", "color": "#6C5CE7", "position": 1 }' ``` الخدمة هي **نوع الموعد** الذي يختاره العميل: ```bash theme={null} curl -X POST "https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/appointments/services" \ -H "Authorization: Bearer $HUECHAT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "استشارة أولية", "description": "استشارة أولى لمدة 30 دقيقة", "duration_minutes": 30, "buffer_before_minutes": 5, "buffer_after_minutes": 10, "price": 250, "currency": "SAR", "color": "#5CB198", "position": 1 }' ``` عيّن الخدمة لموارد مختارة. جسم الطلب مصفوفة UUID، والمصفوفة الفارغة تعني أن كل مورد نشط مؤهل: ```bash theme={null} curl -X PUT "https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/appointments/services/$SERVICE_ID/resources" \ -H "Authorization: Bearer $HUECHAT_API_KEY" \ -H "Content-Type: application/json" \ -d '["'$RESOURCE_ID'"]' ``` ### 3. ضبط ساعات الأسبوع والاستثناءات يستخدم `day_of_week` القيمة `0` للأحد حتى `6` للسبت. تُقاس البداية والنهاية بالدقائق منذ منتصف الليل؛ `540` تعني 09:00 و`1020` تعني 17:00. ```bash theme={null} curl -X POST "https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/appointments/availability/rules/bulk" \ -H "Authorization: Bearer $HUECHAT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "rules": [ {"resource_id":"'$RESOURCE_ID'","day_of_week":0,"start_minute":540,"end_minute":1020,"is_active":true}, {"resource_id":"'$RESOURCE_ID'","day_of_week":1,"start_minute":540,"end_minute":1020,"is_active":true} ] }' ``` استخدم الاستثناء لعطلة أو فتح خاص أو إغلاق مؤقت، واحذف `resource_id` لتطبيقه على كل الموارد: ```bash theme={null} curl -X POST "https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/appointments/availability/exceptions" \ -H "Authorization: Bearer $HUECHAT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "resource_id": "'$RESOURCE_ID'", "kind": "closed", "starts_at": "2026-09-23T00:00:00+03:00", "ends_at": "2026-09-24T00:00:00+03:00", "reason": "إجازة رسمية" }' ``` ## إيجاد وقت بالاسم والنوع والتاريخ يمكن استخدام UUID كمرجع ثابت أو الاسم الدقيق لتدفق سهل للبشر. لا ترسل الشكلين للمنتقي نفسه. ```bash theme={null} curl --get "https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/appointments/slots" \ -H "Authorization: Bearer $HUECHAT_API_KEY" \ --data-urlencode "service_name=استشارة أولية" \ --data-urlencode "resource_name=د. سارة" \ --data-urlencode "date=2026-09-15" \ --data-urlencode "preferred_time=12:00" \ --data-urlencode "limit=20" ``` يُبحث `service_name` و`resource_name` كاسمين دقيقين ونشطين داخل الحساب. استخدم `service_id` و`resource_id` عندما يمكن أن تتغير الأسماء. المورد اختياري؛ حذف منتقي المورد يعيد أوقات كل الموارد المؤهلة. ## إنشاء موعد بالعميل والتاريخ والوقت والنوع يتطلب الإنشاء بمفتاح API قيمة `external_id` ثابتة في النظام المتصل. طولها 1–128 محرف ASCII، تبدأ بحرف لاتيني أو رقم، ثم تستخدم الأحرف والأرقام و`.` و`_` و`:` و`-` فقط. ```bash theme={null} curl -X POST "https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/appointments" \ -H "Authorization: Bearer $HUECHAT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "external_id": "erp-appointment-10492", "service_name": "استشارة أولية", "resource_name": "د. سارة", "date": "2026-09-15", "time": "12:00", "customer_name": "سارة العتيبي", "customer_phone": "+966500000000", "customer_email": "sara@example.com", "status": "booked", "notes": "أُنشئ من موقع الحجز الشريك" }' ``` يمكن بدلًا من ذلك إرسال `service_id` و`resource_id` اختياري و`starts_at` بصيغة RFC3339. إذا حُذف المورد يختار HueChat موردًا مؤهلًا ومتاحًا. مدة الخدمة وفواصلها هي المرجع؛ `ends_at` اختياري ويُستخدم للتحقق ولا يغير مدة الخدمة. `contact_id` اختياري ويتطلب `contacts:read` ويجب أن ينتمي للحساب. ويمكن إرسال اسم العميل وهاتفه وبريده مباشرة من دون إنشاء جهة اتصال. استخدم [واجهة جهات الاتصال وCustomer CDP](/ar/contacts) عندما يحتاج النظام الخارجي إلى حفظ ملف العميل الموحد. `deal_id` اختياري ويتطلب `deals:write`، ويجب أن تكون الصفقة في الحساب وأن يسمح فرعها بالخدمة والمورد. لا تظهر بيانات الصفقة إلا مع `deals:read`. ## إعادة المحاولة من دون حجز مكرر بعد انقطاع الشبكة، أرسل الطلب نفسه مع `external_id` نفسه. يعيد HueChat الموعد الموجود والترويسة: ```text theme={null} X-Idempotent-Replayed: true ``` يصلح ذلك أيضًا رابط صفقة اختياري تعطل بعد إنشاء الموعد. يعيد استخدام المعرّف مع بيانات مختلفة `409 Conflict` ولا يغير الموعد الأول. يمكن إعادة `503` مؤقتة بالطلب نفسه، وتظهر `Retry-After: 0` عندما يبقى ربط الصفقة فقط. تُرفض الحقول المجهولة وأكثر من قيمة JSON والجسم الأكبر من 1 MiB. تتضمن `429` الترويسة `Retry-After: 60` وترويسات `X-RateLimit-*`. ## التحديث وتغيير الوقت والإكمال تتضمن الاستجابات `public_id` وUUID و`version`. استخدم أي معرّف وأرسل أحدث نسخة مع كل تغيير؛ تعيد النسخة القديمة `409`. ```bash theme={null} curl -X PATCH "https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/appointments/$APPOINTMENT_ID/status" \ -H "Authorization: Bearer $HUECHAT_API_KEY" \ -H "Content-Type: application/json" \ -d '{"status":"confirmed","reason":"تأكيد من نظام ERP","version":1}' ``` حالات الإنشاء هي `tentative` و`booked` و`confirmed`. وتقبل التغييرات اللاحقة أيضًا `completed` و`cancelled` و`no_show`. يُحفظ تغيير الحالة وسجله معًا. ```bash theme={null} curl -X PATCH "https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/appointments/$APPOINTMENT_ID/schedule" \ -H "Authorization: Bearer $HUECHAT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "resource_id": "'$RESOURCE_ID'", "service_id": "'$SERVICE_ID'", "starts_at": "2026-09-16T10:30:00+03:00", "version": 2 }' ``` تحتفظ المواعيد المكتملة والملغاة وعدم الحضور بجدولها الأصلي. ## السجل والتقارير يعيد `GET /appointments/{id}` الموعد مع سجل الحالة الزمني. ويعيد `GET /appointments/reports?start=…&end=…` إجماليات كل حالة ونتائج كل خدمة. تستخدم مدد العرض والتوفر والتقرير RFC3339، ويجب أن تكون النهاية بعد البداية وألا تتجاوز 366 يومًا. ## الأمان والحدود المقصودة * يحتفظ HueChat بالمفتاح كتجزئة أحادية الاتجاه فقط. * تُفحص ملكية الحساب والنطاق والانتهاء وقائمة IP الاختيارية والإلغاء وحد المعدل مع كل طلب. * تُحل الأسماء والمعرّفات داخل الحساب فقط؛ يفشل الاسم الدقيق المكرر أو المفقود بدل اختيار سجل غير مقصود. * لا تمنح نطاقات المواعيد صلاحيات ضمنية لجهات الاتصال أو الصفقات أو وكلاء AI. * الأرشفة والاستعادة عمليتا إدارة عامتان لأنهما تحتفظان بالتاريخ. الحذف الدائم للموارد والخدمات ليس ضمن عقد التكامل الموثق. * يبقى ربط المورد بوكيل AI تدفق إدارة للذكاء الاصطناعي، وليس عملية تكامل مواعيد. راجع [مرجع API التفاعلي](/ar/api-reference/overview) لكل حقل طلب ومخطط استجابة وحالة خطأ.