> ## 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.

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

> مزامنة تقويم HueChat مع نظام العيادة أو المستشفى المعتمد، مثل Oracle Health (Cerner) أو Epic أو InterSystems TrakCare أو نظام إدارة العيادة، عبر REST أو HL7 FHIR R4.

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

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

## خطوات الربط

<Steps>
  <Step title="يعتمد فريق HueChat الحساب">
    يتاح الربط مع أنظمة المواعيد للحسابات التي يعتمدها فريق HueChat أثناء
    التهيئة. وقبل ذلك تُرفض طلبات المزامنة بالرمز `403`.
  </Step>

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

  <Step title="يرسل النظام حجوزاته">
    يُحفظ كل حجز يرسله النظام كما هو فيه. وتعرض **المواعيد ← إعدادات الحجز ←
    الربط مع نظام المواعيد** آخر حجز مستلم وأي حجز تعذّر على HueChat حفظه.
  </Step>
</Steps>

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

## ما يحفظه HueChat

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

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

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

## إرسال حجز

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

```bash theme={null}
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 المورد والخدمة بهذا الترتيب:

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

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

### المرضى

يربط HueChat الحجز بجهة اتصال موجودة عبر `contact_id`، ثم عبر
`patient_identifier` (معرّف جهة الاتصال مثل رقم الملف الطبي)، ثم عبر رقم الجوال.
وتُكمل البيانات الناقصة من جهة الاتصال تلك. لا تنشئ المزامنة جهات اتصال؛ أنشئ
المرضى عبر [واجهة جهات الاتصال](/ar/contacts) مع رقم الملف قيمةً لـ`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`. يُحفظ كل حجز وحده، فلا يوقف حجز مرفوض بقية الحجوزات.

```json theme={null}
{
  "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>`.

```json theme={null}
{
  "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`.