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

تحجز العيادات والمستشفيات مرضاها عادةً في نظامها المعتمد. ينسخ الربط مع نظام المواعيد كل حجز من ذلك النظام إلى HueChat، فتصل تذكيرات واتساب والنماذج والمتابعة إلى كل مريض، بمن فيهم مرضى الحضور المباشر ومن حُجز لهم قبل الموعد بدقائق. يعمل الربط بالطريقة نفسها مع نظام عيادة صغيرة ومع محرك التكامل في مستشفى يستخدم Oracle Health (Cerner) أو Epic أو InterSystems TrakCare. أرسل JSON عبر REST، أو أرسل موارد HL7 FHIR R4 من نوع Appointment.

خطوات الربط

يعتمد فريق HueChat الحساب

يتاح الربط مع أنظمة المواعيد للحسابات التي يعتمدها فريق HueChat أثناء التهيئة. وقبل ذلك تُرفض طلبات المزامنة بالرمز 403.

ينشئ مدير الحساب مفتاحًا للنظام

من HueChat ← الحساب ← واجهة المطور اختر القالب نظام المواعيد، وهو يمنح appointments:sync وappointments:read وcontacts:read. أنشئ مفتاحًا واحدًا لكل نظام وسلّمه لفريق دعم ذلك النظام.

يرسل النظام حجوزاته

يُحفظ كل حجز يرسله النظام كما هو فيه. وتعرض المواعيد ← إعدادات الحجز ← الربط مع نظام المواعيد آخر حجز مستلم وأي حجز تعذّر على HueChat حفظه.

لا يُعامل كنظام مواعيد إلا مفتاح REST API يحمل appointments:sync على حساب معتمد. ويُرفض تسجيل دخول الموظفين ورموز الوصول الشخصية، فلا تعمل المزامنة بصلاحيات حساب شخص كاملة، ولا تتوقف عند دخوله من جهاز آخر، ولا يظهر موظف واحد كمنشئ لكل الحجوزات.

ما يحفظه HueChat

يُحفظ الحجز القادم من الربط كما هو في النظام، مع source: "sync":

الزيارات السابقة وزيارات نفس اليوم والحضور المباشر، والأوقات خارج شبكة الفترات أو خارج ساعات العمل في HueChat
الأطباء أو الغرف أو الخدمات المؤرشفة
أي حالة من حالات الموعد
الحجز المزدوج المقصود، حين يستقبل الطبيب مريضين في الوقت نفسه

أما قنوات الحجز في HueChat (وكلاء الذكاء الاصطناعي والنماذج والموظفون) فلا تتداخل حجوزاتها أبدًا، وتتجنب الأوقات التي تشغلها الحجوزات المتزامنة. ولا يُنقل الحجز المتزامن إلا من النظام الذي يملكه، فلا يمكن سحبه إلى وقت آخر داخل HueChat. ولا تُعرض الأطباء والغرف التي أنشأها النظام على قنوات الحجز في HueChat، لأن HueChat لا يستطيع إعادة كتابة الحجز في ذلك النظام.

إرسال حجز

ينشئ PUT /appointments/external/{externalId} الحجز أو يحدّثه إلى النسخة المرسلة. استخدم معرّف الحجز في نظامك قيمةً لـexternalId.

curl -X PUT "https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/appointments/external/his-main:A-10492" \
  -H "Authorization: Bearer $HUECHAT_SYNC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_updated_at": "2026-09-22T09:58:00Z",
    "status": "booked",
    "starts_at": "2026-09-22T13:00:00+03:00",
    "ends_at": "2026-09-22T13:20:00+03:00",
    "resource_code": "Practitioner/482",
    "resource_name": "Dr. Sara Ali",
    "service_code": "DENT-CONSULT",
    "service_name": "Dental consultation",
    "patient_identifier": "MRN-000205",
    "customer_name": "Example Patient",
    "customer_phone": "+966500000000"
  }'

يعيد الطلب الأول 201، وتعيد الطلبات اللاحقة 200 مع الترويسة X-HueChat-Sync-Result التي تبيّن ما حدث:

النتيجة	المعنى
`created`	حجز جديد
`updated`	يحمل HueChat الآن النسخة المرسلة
`unchanged`	النسخة المرسلة هي نفسها الموجودة في HueChat
`stale`	أُرسلت نسخة أقدم مما يحمله HueChat فتم تجاهلها

ترتيب التحديثات

أرسل source_updated_at، وهو آخر وقت عدّل فيه نظامك الحجز (meta.lastUpdated في FHIR وMSH-7 في HL7). وإذا وصلت الرسائل بغير ترتيبها تجاهل HueChat التحديث الأقدم مما لديه، فلا تعيد رسالة متأخرة الحجز إلى حالة سابقة. أما إعادة إرسال النسخة نفسها بوقت أحدث فتسجّل الوقت فقط.

الأطباء والغرف والخدمات

يطابق HueChat المورد والخدمة بهذا الترتيب:

معرّف HueChat (resource_id وservice_id).
رمزك الخاص (resource_code وservice_code)، مثل معرّف الطبيب أو الموقع أو الإجراء.
الاسم (resource_name وservice_name) مع تجاهل حالة الأحرف والمسافات وعلامات الترقيم، فيطابق Dr.Sara Ali الاسم Dr. Sara Ali.

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

المرضى

يربط HueChat الحجز بجهة اتصال موجودة عبر contact_id، ثم عبر patient_identifier (معرّف جهة الاتصال مثل رقم الملف الطبي)، ثم عبر رقم الجوال. وتُكمل البيانات الناقصة من جهة الاتصال تلك. لا تنشئ المزامنة جهات اتصال؛ أنشئ المرضى عبر واجهة جهات الاتصال مع رقم الملف قيمةً لـidentifier إذا كانت دعوات النماذج يجب أن تصل إليهم.

الحالات

يقبل HueChat حالاته الخاصة، وحالات Appointment.status في HL7 FHIR R4، ورموز حالة المنفّذ في HL7 v2 SIU:

المُرسل	يُحفظ كـ
`booked` و`Overbook`	`booked`
`tentative` و`proposed` و`pending` و`waitlist`	`tentative`
`confirmed` و`arrived` و`checked-in` و`Started`	`confirmed`
`completed` و`fulfilled` و`Complete`	`completed`
`cancelled` و`Canceled` و`DC`	`cancelled`
`no_show` و`noshow`	`no_show`
`entered-in-error` و`Deleted`	`cancelled` مع السبب “Entered in error”

أضف cancellation_reason إلى الحجز الملغى للاحتفاظ بسبب الإلغاء في نظامك.

حذف حجز

يُبقي DELETE /appointments/external/{externalId}?reason=… الحجز في HueChat ملغى مع سجله. ويعيد المعرّف غير المعروف 204.

إرسال حجوزات كثيرة

يقبل POST /appointments/sync حتى 200 حجز، ويتبع كل عنصر قواعد الطلب المفرد ويجب أن يحمل external_id. يُحفظ كل حجز وحده، فلا يوقف حجز مرفوض بقية الحجوزات.

{
  "appointments": [
    { "external_id": "his-main:A-10492", "status": "booked", "starts_at": "2026-09-22T13:00:00+03:00", "resource_code": "Practitioner/482", "service_code": "DENT-CONSULT", "patient_identifier": "MRN-000205" },
    { "external_id": "his-main:A-10493", "status": "fulfilled", "starts_at": "2026-09-22T11:40:00+03:00", "ends_at": "2026-09-22T12:05:00+03:00", "resource_code": "Practitioner/482", "service_code": "DENT-CONSULT", "customer_name": "Walk-in patient" }
  ]
}

تعرض الاستجابة نتيجة لكل حجز بترتيب الطلب، مع مجاميع created وupdated وunchanged وstale وfailed.

المطابقة

يعرض GET /appointments/sync?start=…&end=… كل حجز له معرّف خارجي يبدأ في الفترة (حتى 31 يومًا) مرتبًا حسب وقت البدء، ويُستخدم next_cursor للصفحة التالية. قارنه بجدولك وأعد إرسال ما يختلف.

متابعة حالة الربط

يعيد GET /appointments/sync/status:

مفاتيح أنظمة المواعيد في الحساب ووقت آخر استخدام لكل منها
آخر وقت تغيّر فيه حجز متزامن، وعدد ما تغيّر خلال آخر 24 ساعة
الحجوزات التي رفضها HueChat إلى أن تنجح نسخة لاحقة منها

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

HL7 FHIR R4

تستطيع محركات التكامل التي تنتج FHIR R4 إرسال موارد Appointment كما هي:

الطلب	الغرض
`GET /fhir/R4/metadata`	بيان القدرات
`PUT /fhir/R4/Appointment/{id}`	إنشاء الحجز أو تحديثه
`GET /fhir/R4/Appointment/{id}`	قراءة الحجز الموجود في HueChat
`DELETE /fhir/R4/Appointment/{id}`	إلغاء الحجز مع الاحتفاظ به
`POST /fhir/R4`	حزمة `batch` فيها حتى 200 عنصر Appointment

العنوان الأساسي هو https://app.huechat.ai/api/v2/accounts/{accountId}/fhir/R4. أضف ?source= باسم قصير للنظام المرسل، مثل ?source=oracle-main، حتى لا يتشارك نظاما FHIR في الحساب نفسه المعرّفات. ويصبح المعرّف الخارجي للحجز <source>:Appointment:<id>.

{
  "resourceType": "Appointment",
  "id": "A-10492",
  "meta": { "lastUpdated": "2026-09-22T09:58:00Z" },
  "status": "booked",
  "serviceType": [{ "coding": [{ "code": "DENT-CONSULT", "display": "Dental consultation" }] }],
  "start": "2026-09-22T10:00:00Z",
  "end": "2026-09-22T10:20:00Z",
  "contained": [
    { "resourceType": "Patient", "id": "patient", "identifier": [{ "value": "MRN-000205" }], "name": [{ "text": "Example Patient" }], "telecom": [{ "system": "phone", "value": "+966500000000", "use": "mobile" }] },
    { "resourceType": "Practitioner", "id": "doctor", "identifier": [{ "value": "Practitioner/482" }], "name": [{ "text": "Dr. Sara Ali" }] }
  ],
  "participant": [
    { "actor": { "reference": "#patient" } },
    { "actor": { "reference": "#doctor" } }
  ]
}

FHIR	HueChat
مشارك من نوع `Practitioner` أو `PractitionerRole` (وإلا `Location` ثم `HealthcareService`)	المورد: معرّفه هو الرمز، واسمه أو قيمة display هي الاسم
`serviceType`، وإلا `appointmentType`	رمز الخدمة واسمها
مشارك من نوع `Patient`	المريض: المعرّف والاسم والجوال والبريد من Patient المضمَّن، أو قيمة display في المرجع
`start` و`end` و`minutesDuration`	الوقت والمدة
`meta.lastUpdated`	`source_updated_at`
`comment`، وإلا `description`	الملاحظات
`cancelationReason`	سبب الإلغاء

تعود الأخطاء على شكل موارد OperationOutcome. وهذه النقطة جزء من FHIR مخصص للكتابة، وليست خادم FHIR عامًا.

HL7 v2 SIU

وجّه رسائل SIU عبر محرك التكامل لديك، مثل Rhapsody أو Mirth أو InterSystems أو Cloverleaf، إلى نقطة REST أو FHIR:

حدث SIU	الطلب
S12 حجز جديد، S13 إعادة جدولة، S14 تعديل	`PUT` بتفاصيل الحجز الحالية
S15 إلغاء	`PUT` مع `status: "cancelled"`
S17 حذف	`DELETE`
S26 عدم حضور	`PUT` مع `status: "noshow"`

استخدم MSH-7 قيمةً لـsource_updated_at، وحالة المنفّذ في SCH قيمةً لـstatus.

قائمة التحقق الأمنية

خصص لكل نظام مفتاحًا مستقلًا، وقيّده بعناوين IP الخاصة بالنظام من واجهة المطور.
امنح appointments:sync وappointments:read وcontacts:read فقط.
دوّر المفتاح من واجهة المطور دون توقف، وألغِه عند إيقاف النظام.
أرسل ما تحتاجه التذكيرات والنماذج فقط، وأبعد التفاصيل السريرية عن notes.

ابدأ هنا

العمل مع الواجهة

التكامل

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

خطوات الربط

ما يحفظه HueChat

إرسال حجز

ترتيب التحديثات

الأطباء والغرف والخدمات

المرضى

الحالات

حذف حجز

إرسال حجوزات كثيرة

المطابقة

متابعة حالة الربط

HL7 FHIR R4

HL7 v2 SIU

قائمة التحقق الأمنية

​خطوات الربط

​ما يحفظه HueChat

​إرسال حجز

​ترتيب التحديثات

​الأطباء والغرف والخدمات

​المرضى

​الحالات

​حذف حجز

​إرسال حجوزات كثيرة

​المطابقة

​متابعة حالة الربط

​HL7 FHIR R4

​HL7 v2 SIU

​قائمة التحقق الأمنية

خطوات الربط

ما يحفظه HueChat

إرسال حجز

ترتيب التحديثات

الأطباء والغرف والخدمات

المرضى

الحالات

حذف حجز

إرسال حجوزات كثيرة

المطابقة

متابعة حالة الربط

HL7 FHIR R4

HL7 v2 SIU

قائمة التحقق الأمنية