# المواعيد

> الخدمات والفريق والمواعيد بالجملة لجدولك

- الصفحة: https://tbit.app/ar/docs/api/appointments
- عنوان URL الأساسي: `https://rest-api.tbit.app/v1`
- المصادقة: ترويسة `X-API-Key` تحمل مفتاحك في كل طلب (تقرأه الأمثلة من متغير البيئة `TBIT_API_KEY`)

## نظرة عامة

ما تحتاجه لإدارة جدول أعمالك من نظام آخر: الخدمات التي تُحجز مع من يقدمها، الفريق، وتحميل المواعيد بالجملة. هذا هو ما تفعله أدوات MCP ‏list_services و list_collaborators و import_appointments، بنفس أسماء الحقول.

## نقاط النهاية

| الطريقة | المسار | الوصف |
| --- | --- | --- |
| `GET` | `/v1/services` | الخدمات التي تُحجز، ومن يقدمها |
| `GET` | `/v1/collaborators` | الفريق: الاسم، البريد، الدور والخدمات التي يقدمها |
| `POST` | `/v1/appointments/import` | تحميل حتى 200 موعد في طلب واحد |

## عرض الخدمات

كل خدمة تحمل id و name و duration_minutes و price و currency و location و active و collaborators (id و name و email لمن يقدمها). الـ id هو ما تطلبه كـ service_id عند استيراد المواعيد. الخدمات التي تُؤجَّر (غرف، قاعات، مركبات) لا تظهر هنا.

`GET /v1/services`

```bash
curl "https://rest-api.tbit.app/v1/services" \
  -H "X-API-Key: $TBIT_API_KEY"
```

الاستجابة:

```json
{
  "data": [
    {
      "id": "6a0f3c2e9b1d4a0012ab34cd",
      "name": "Endodoncia",
      "duration_minutes": 60,
      "price": 350000,
      "currency": "COP",
      "location": "Sede norte · Calle 72 # 7-41",
      "active": true,
      "collaborators": [
        {
          "id": "6a0f3c2e9b1d4a0012ab0001",
          "name": "Geral Díaz",
          "email": "geral@tuclinica.co"
        }
      ]
    }
  ]
}
```

## عرض الفريق

كل شخص يحمل id و name و email و role و attends_appointments (هل يقدم المواعيد) و service_ids (الخدمات التي يقدمها). عندما لا يكون للشخص اسم محمّل، يأتي name فارغًا: تعرّف عليه من بريده.

`GET /v1/collaborators`

```bash
curl "https://rest-api.tbit.app/v1/collaborators" \
  -H "X-API-Key: $TBIT_API_KEY"
```

الاستجابة:

```json
{
  "data": [
    {
      "id": "6a0f3c2e9b1d4a0012ab0001",
      "name": "Geral Díaz",
      "email": "geral@tuclinica.co",
      "role": "ADMIN",
      "attends_appointments": true,
      "service_ids": [
        "6a0f3c2e9b1d4a0012ab34cd"
      ]
    }
  ]
}
```

## استيراد المواعيد

أرسل حتى 200 موعدًا في كل استدعاء ضمن appointments. كل صف يحمل phone (مع رمز الدولة، مثل 573001234567: يُبحث عن جهة الاتصال برقم الهاتف، وإن لم تكن موجودة تُنشأ) أو contact_id (جهة اتصال موجودة بالفعل: يذهب الموعد إلى تلك البطاقة حتى لو لم يكن لديها رقم هاتف، كمن يكتب بمستخدم WhatsApp؛ وإذا أرسلت phone أيضًا فلا يُستخدم إلا للإشعار)، وcontact_name وemail اختياريان، والخدمة (service_id أو service_name، الاسم الدقيق دون اعتبار لحالة الأحرف)، ومن يقدّم الخدمة (collaborator_id أو collaborator_email؛ وإذا كان شخص واحد فقط يقدّم الخدمة يمكنك حذفه)، وstart بصيغة ISO 8601 (بدون منطقة زمنية يُقرأ في المنطقة الزمنية للنشاط التجاري)، وend اختياري (افتراضيًا start زائد مدة الخدمة)، وexternal_id (مفتاح الحدث في نظامك: إعادة الاستيراد لا تكرره) وnotes.

خيارات، كلها في المستوى الأول من الجسم: notify_customer (افتراضيًا false: لا يصل للعميل تأكيد؛ true يرسله كأي موعد)، و send_reminders (افتراضيًا true)، و release_blocks (true يزيل حجوزات ذلك الشخص المتقاطعة مع الموعد)، و on_existing (skip أو update: إذا وُجد موعد بنفس external_id، يتركه كما هو أو ينقله دون إشعار أحد) و dry_run (true يتحقق من كل شيء ويقول ما سيفعل، دون كتابة أي شيء). ابدأ دائمًا بـ dry_run.

تقول الاستجابة لكل صف ما حدث: status هو created أو updated أو skipped أو failed (would_create أو would_update مع dry_run)، مع appointment_id و contact_id، وإن فشل، error مع السبب بالكلمات («أندريس لا يقدم علاج الجذور؛ يقدمه: جيرالد دياز.»). صف سيئ لا يوقف الباقي. احفظ import_id: هو ما تحتاجه للتراجع.

`POST /v1/appointments/import`

```bash
curl -X POST "https://rest-api.tbit.app/v1/appointments/import" \
  -H "X-API-Key: $TBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dry_run": true,
    "appointments": [
      {
        "phone": "573001234567",
        "contact_name": "Ana Pérez",
        "service_name": "Endodoncia",
        "collaborator_email": "geral@tuclinica.co",
        "start": "2026-11-20T10:00",
        "external_id": "gcal-7f3k2"
      }
    ]
  }'
```

الاستجابة:

```json
{
  "data": {
    "import_id": null,
    "dry_run": true,
    "created": 1,
    "updated": 0,
    "skipped": 0,
    "failed": 0,
    "results": [
      {
        "index": 0,
        "external_id": "gcal-7f3k2",
        "status": "would_create",
        "contact_id": "6a0f3c2e9b1d4a0012ab9f10"
      }
    ]
  }
}
```

## التراجع عن استيراد

أرسل فقط undo_import_id مع import_id الذي أعادته عملية الاستيراد: كل المواعيد التي أنشأها ذلك الاستيراد تصبح ملغاة، دون إشعار أحد، ويصبح external_id الخاص بها حرًا لإعادة استيرادها.

`POST /v1/appointments/import`

```bash
curl -X POST "https://rest-api.tbit.app/v1/appointments/import" \
  -H "X-API-Key: $TBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "undo_import_id": "6a1e0b7c5d4f3a0012cd5678"
  }'
```

الاستجابة:

```json
{
  "data": {
    "import_id": "6a1e0b7c5d4f3a0012cd5678",
    "cancelled": 198,
    "already_cancelled": 2,
    "failed": []
  }
}
```

## القواعد والأخطاء

- على الشخص أن يقدم تلك الخدمة. وإلا يفشل الصف ويقول الخطأ من يقدمها فعلًا.
- لا يمكن أن يتقاطع موعد مع آخر لنفس الشخص، ولا مع صف آخر من نفس الدفعة. إذا تقاطع مع حجز في الأجندة، يفشل الصف إلا إذا أرسلت release_blocks: true.
- الدفعة التي لا يمكن قراءتها كاملة (فارغة، أكثر من 200 صف، حقل غير معروف في الجسم) تستجيب بـ 400 VALIDATION_ERROR ولا تكتب شيئًا.
- قد تستغرق الدفعة الكبيرة وقتًا: كل موعد ينشئ طلبه وجهة اتصاله. إذا تجاوزت دفعاتك 100 موعد، قسّمها إلى طلبات أصغر.
