المواعيد والجدولة

​

قبل البدء

​

المصادقة واختبار طلب موعد

curl -i --get "https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/appointments" \
  -H "Authorization: Bearer $HUECHAT_API_KEY" \
  --data-urlencode "start=2026-09-01T00:00:00+03:00" \
  --data-urlencode "end=2026-09-02T00:00:00+03:00"

​

التغطية الكاملة للواجهة

​

القراءة والبحث والحجز

​

الربط مع أنظمة المواعيد

​

إعدادات المدير

​

أتمتة تذكيرات واتساب

​

شرح عمليات القراءة واحدةً واحدة

• 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. يعيد وقت البداية والنهاية بصيغة مطلقة ومحلية لكل مورد متاح. date تاريخ مدني حسب منطقة الحساب الزمنية، والمصفوفة الفارغة نتيجة ناجحة ليوم مغلق أو ممتلئ وليست خطأ API.
• GET /appointments/reports: يعيد إجماليات الحالات والحجوزات المنشأة بالذكاء الاصطناعي وتوزيع النتائج حسب الخدمة. المدة الافتراضية شهر وأقصاها 366 يومًا.

​

شرح عمليات الكتابة واحدةً واحدة

• POST /appointments/history: نقطة ترحيل مقيّدة للحسابات المعتمدة، ويجب أن يحمل مفتاح REST النطاق appointments:history:write. يقبل خدمة وموردًا نشطين أو مؤرشفين بالـUUID أو الاسم الدقيق، ويحفظ حدث الحالة الأول من دون فحص الأوقات الحية أو إرسال إشعار حجز أو تذكير. راجع استيراد المواعيد التاريخية.
• 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 والدقائق منذ منتصف الليل. الحقلان effective_from وeffective_to تاريخان مدنيان اختياريان وشاملان حسب منطقة الحساب الزمنية، وis_active:false يبقي المورد مغلقًا صراحةً.
• POST /appointments/availability/rules/bulk: يتحقق من جميع القواعد أولًا ثم يحفظها معًا، ولذلك لا يترك جدولًا نصف محدث. يستبدل فقط أزواج المورد/اليوم المرسلة ولا يحذف الأيام غير المرسلة.
• POST /appointments/availability/exceptions: ينشئ فترة open أو closed؛ يجب أن تكون أوقاتها RFC3339 مع فرق UTC صريح. حذف resource_id يجعلها عامة لكل الموارد. يضيف open فترة محددة، بينما يزيل closed أي وقت متداخل.
• DELETE /appointments/availability/exceptions/{exceptionId}: يحذف الاستثناء المحدد داخل الحساب ولا يمس سجل المواعيد.

​

عمليات التذكير

• GET /appointments/reminders: يعيد التوقيت ونطاق الطبيب/المورد وصندوق واتساب والقالب المعتمد والربط بالمتغيرات وحالة التفعيل، ولا ينشئ قاعدة.
• POST /appointments/reminders: يتحقق أن المورد والصندوق وقالب UTILITY المعتمد كلها للحساب نفسه. استخدم is_active:false للحفظ والمراجعة من دون إرسال.
• PUT /appointments/reminders/{reminderId}: يستبدل القاعدة كاملة. عند تفعيلها أو تغيير توقيتها أو موردها أو صندوقها أو قالبها أو ربطها، يبدأ حد تفعيل جديد ولا تُرسل تذكيرات كان موعدها قبل هذا الحد.
• DELETE /appointments/reminders/{reminderId}: تعطيل يحافظ على سجل التسليم بدل حذف الدليل التاريخي.
• GET /appointments/reminder-deliveries: يرشح اختياريًا بـUUID الموعد أو معرّف جهة الاتصال وبحد من 1 إلى 100. تعني sent أن واتساب قبل الطلب، وskipped أن شرط أمان منع الإرسال، وfailed رفضًا مؤكدًا، وuncertain أن النتيجة لا يمكن إثباتها ولذلك لا يعاد الإرسال تلقائيًا.

​

ضبط نموذج الجدولة

​

1. حفظ إعدادات الحساب

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. إنشاء مورد ونوع موعد

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
  }'

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
  }'

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. ضبط ساعات الأسبوع والاستثناءات

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":600,"end_minute":1320,"effective_from":"2026-09-12","effective_to":"2026-09-30","is_active":true},
      {"resource_id":"'$RESOURCE_ID'","day_of_week":1,"start_minute":600,"end_minute":1320,"effective_from":"2026-09-12","effective_to":"2026-09-30","is_active":true}
    ]
  }'

​

أولوية التوفر والساعات الافتراضية

1. المورد الذي لم تُنشأ له أي قاعدة أسبوعية يحصل مبدئيًا على 08:00–18:00 فقط لتسهيل بدء استخدام المورد الجديد.
2. بعد وجود أي قاعدة للمورد يتوقف هذا السلوك الافتراضي. لا تفتح الوقت إلا قاعدة مفعلة تطابق يوم الأسبوع وتقع داخل حدود التاريخ الشاملة. القاعدة المعطلة أو اليوم غير المرسل أو التاريخ خارج النطاق يعني أن المورد مغلق.
3. استثناء open المطابق يضيف فترته الدقيقة حتى لو كانت القاعدة الأسبوعية معطلة أو خارج نطاقها. واستثناء closed يزيل أي وقت متداخل وتكون له الأولوية.
4. يجب أن تقع مدة الخدمة وهوامشها بالكامل داخل فترة مفتوحة، ثم تُطبق مهلة الحجز والحد الأقصى المسبق والحجوزات الموجودة.

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": "إجازة رسمية"
  }'

​

إيجاد وقت بالاسم والنوع والتاريخ

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"

​

إنشاء موعد بالعميل والتاريخ والوقت والنوع

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": "أُنشئ من موقع الحجز الشريك"
  }'

​

استيراد المواعيد التاريخية

curl -X POST "https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/appointments/history" \
  -H "Authorization: Bearer $HUECHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "ehr-appointment-10492",
    "source_system": "clinic-ehr",
    "service_name": "استشارة أولية",
    "resource_name": "د. سارة",
    "starts_at": "2025-09-15T09:00:00Z",
    "ends_at": "2025-09-15T09:30:00Z",
    "customer_name": "سارة العتيبي",
    "customer_phone": "+966500000000",
    "status": "fulfilled",
    "status_changed_at": "2025-09-15T09:35:00Z",
    "notes": "مستورد من نظام العيادة السابق"
  }'

​

إعادة المحاولة من دون حجز مكرر

X-Idempotent-Replayed: true

​

التحديث وتغيير الوقت والإكمال

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}'

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
  }'

​

ضبط تذكيرات مواعيد واتساب

​

مثال قبل الموعد بـ24 ساعة

curl -X POST "https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/appointments/reminders" \
  -H "Authorization: Bearer $HUECHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "تذكير قبل 24 ساعة",
    "resource_id": "10dfa9db-a206-443a-a6da-8c0eb2964377",
    "timing_type": "before_start",
    "minutes_before": 1440,
    "send_minute": null,
    "inbox_id": 12,
    "template_id": "11111111-2222-3333-4444-555555555555",
    "bindings": [
      {"field": "customer.first_name"},
      {"field": "appointment.date"},
      {"field": "appointment.time"},
      {"field": "resource.name"}
    ],
    "is_active": false
  }'

​

الإرسال في اليوم السابق

​

ضمانات التسليم والإيصالات

curl "https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/appointments/reminder-deliveries?appointment_id=$APPOINTMENT_UUID&limit=50" \
  -H "Authorization: Bearer $HUECHAT_API_KEY"

​

السجل والتقارير

​

الأمان والحدود المقصودة

• يحتفظ HueChat بالمفتاح كتجزئة أحادية الاتجاه فقط.
• تُفحص ملكية الحساب والنطاق والانتهاء وقائمة IP الاختيارية والإلغاء وحد المعدل مع كل طلب.
• تُحل الأسماء والمعرّفات داخل الحساب فقط؛ يفشل الاسم الدقيق المكرر أو المفقود بدل اختيار سجل غير مقصود.
• لا تمنح نطاقات المواعيد صلاحيات ضمنية لجهات الاتصال أو الصفقات أو وكلاء AI.
• الأرشفة والاستعادة عمليتا إدارة عامتان لأنهما تحتفظان بالتاريخ. الحذف الدائم للموارد والخدمات ليس ضمن عقد التكامل الموثق.
• يبقى ربط المورد بوكيل AI تدفق إدارة للذكاء الاصطناعي، وليس عملية تكامل مواعيد.