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

​

قبل البدء

​

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

​

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

​

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

​

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

• 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. حفظ إعدادات الحساب

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":540,"end_minute":1020,"is_active":true},
      {"resource_id":"'$RESOURCE_ID'","day_of_week":1,"start_minute":540,"end_minute":1020,"is_active":true}
    ]
  }'

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

​

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

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

​

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

​

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

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