# دليل استخدام Postman Collection — كل روابط API

هذا الملف شرح شامل لكل الـ 45 endpoint في `api/v1/*`، مع ملف Postman Collection جاهز
للاستيراد مباشرة:

📁 **الملف**: [`postman/BST-Clinics-Mobile-API.postman_collection.json`](postman/BST-Clinics-Mobile-API.postman_collection.json)

كل الاستجابات بنفس الظرف الموحّد الموثّق في [`00-api-response-format.md`](00-api-response-format.md).
للتفاصيل الكاملة لكل مجموعة endpoints (أمثلة استجابة ناجحة/فاشلة كاملة) راجع الملفات:
[`02-lookups-doctors-clinics.md`](02-lookups-doctors-clinics.md)،
[`03-booking.md`](03-booking.md)، [`04-patient-profile.md`](04-patient-profile.md)،
[`05-medical-records.md`](05-medical-records.md)، [`06-chat.md`](06-chat.md)،
[`07-offers-home-notifications.md`](07-offers-home-notifications.md). هذا الملف يضيف تفاصيل
Auth والـ Settings (لم تكن موثّقة قبل كده) بالإضافة لجدول شامل واحد لكل الروابط.

---

## 1) كيفية الاستيراد والاستخدام في Postman

1. **Import** → اختار الملف `postman/BST-Clinics-Mobile-API.postman_collection.json`.
2. المجموعة فيها متغيرات (Collection Variables) جاهزة — تقدر تعدّلها من تبويب **Variables**
   بتاع الـ Collection نفسها:

   | المتغيّر | القيمة الافتراضية | الوصف |
   |---|---|---|
   | `base_url` | `http://erp.local/api/v1` | غيّره لو السيرفر عندك على دومين/بورت مختلف |
   | `lang` | `ar` | `ar` أو `en` — بيتبعت في هيدر `Accept-Language` |
   | `token` | فاضي | بيتحدد **تلقائيًا** بعد عمل Register أو Login (فيه Test Script بياخده من الاستجابة) |
   | `doctor_id`, `clinic_profile_id`, `branch_id`, `specialty_id` | `1`, `1`, `3`, `1` | لتجربة سريعة، غيّرها حسب بياناتك |
   | `booking_id` | `1` | بيتحدّث تلقائيًا لأحدث حجز بعد نجاح "Create Booking" |
   | `record_id`, `category_id`, `notification_id` | حسب الحاجة | حطها يدويًا من نتائج الطلبات اللي قبلها |
   | `booking_date`, `booking_time` | `2026-12-01`, `10:00` | أي تاريخ مستقبلي وأي وقت بصيغة `H:i` |

3. **مسار التجربة المقترح** (بالترتيب):
   1. مجموعة **01 - Auth** → نفّذ **Register** (أو **Login** لو الحساب موجود بالفعل) —
      التوكن هيتحفظ تلقائيًا.
   2. مجموعة **03 - Lookups & Browsing** → جرّب **Specialties**, **Doctors - Search/List**,
      **Doctor Detail** لمعرفة `doctor_id`/`clinic_profile_id` حقيقيين من بياناتك.
   3. مجموعة **05 - Patient Profile** → نفّذ **Update Medical Profile** (لازم قبل أول حجز).
   4. مجموعة **04 - Booking** → **Available Slots** ثم **Create Booking** (بيحفظ `booking_id`
      تلقائيًا) ثم جرّب الباقي.
   5. باقي المجموعات (Medical Records / Chat / Offers / Notifications) مستقلة عن بعضها.

4. **الهيدرز الأساسية** لكل طلب (متضمّنة بالفعل في كل الطلبات):
   - `Accept: application/json` — **إجباري**، من غيره أي مسار محمي بيرجع صفحة HTML بدل JSON.
   - `Accept-Language: {{lang}}` — يحدد لغة الرسائل والحقول المترجمة.
   - `Authorization: Bearer {{token}}` — مُدار تلقائيًا عبر Collection-level Auth (Bearer)،
     المسارات العامة فيها `noauth` override صريح فمش هتاخد Header ده.

---

## 2) جدول كل الروابط (45 endpoint)

| # | Method | المسار (بعد `/api/v1`) | محمي؟ | الوصف |
|---|---|---|---|---|
| 1 | POST | `auth/register` | لا | إنشاء حساب |
| 2 | POST | `auth/login` | لا | تسجيل الدخول |
| 3 | POST | `auth/forgot-password` | لا | إرسال لينك إعادة تعيين كلمة المرور |
| 4 | POST | `auth/reset-password` | لا | إتمام إعادة التعيين |
| 5 | POST | `auth/logout` | نعم | خروج (الجهاز الحالي) |
| 6 | POST | `auth/logout-all` | نعم | خروج من كل الأجهزة |
| 7 | GET | `auth/me` | نعم | بيانات المستخدم الحالي |
| 8 | PUT | `auth/profile` | نعم | تحديث البيانات الأساسية |
| 9 | POST | `auth/avatar` | نعم | رفع صورة البروفايل |
| 10 | PUT | `auth/password` | نعم | تغيير كلمة المرور |
| 11 | DELETE | `auth/account` | نعم | حذف الحساب |
| 12 | GET | `settings` | لا | إعدادات عامة للتطبيق |
| 13 | GET | `settings/onboarding` | لا | شرائح الـ Onboarding |
| 14 | GET | `settings/pages/{type}` | لا | صفحة ثابتة (about/privacy_policy/privacy_terms) |
| 15 | GET | `settings/faqs` | لا | الأسئلة الشائعة |
| 16 | POST | `settings/contact` | لا | تواصل معنا |
| 17 | POST | `settings/app-review` | اختياري | تقييم التطبيق |
| 18 | GET | `lookups/specialties` | لا | كل التخصصات |
| 19 | GET | `clinics` | لا | كل العيادات النشطة |
| 20 | GET | `doctors` | لا | بحث/تصفح الدكاترة |
| 21 | GET | `doctors/{doctor}` | لا | بروفايل دكتور |
| 22 | GET | `doctors/{doctor}/reviews` | لا | تقييمات دكتور |
| 23 | GET | `home` | لا | الشاشة الرئيسية المجمّعة |
| 24 | GET | `doctors/{doctor}/clinics/{clinicProfile}/slots` | نعم | المواعيد المتاحة |
| 25 | POST | `bookings` | نعم | إنشاء حجز |
| 26 | GET | `bookings/mine` | نعم | حجوزاتي |
| 27 | GET | `bookings/{booking}` | نعم | تفاصيل حجز |
| 28 | POST | `bookings/{booking}/cancel` | نعم | إلغاء حجز |
| 29 | POST | `bookings/{booking}/reschedule` | نعم | تأجيل حجز |
| 30 | POST | `bookings/{booking}/review` | نعم | تقييم بعد الزيارة |
| 31 | GET | `medical-history-options` | نعم | قائمة الأمراض/الأدوية |
| 32 | GET | `patient-profile/medical` | نعم | عرض الملف الطبي |
| 33 | PUT | `patient-profile/medical` | نعم | تحديث الملف الطبي |
| 34 | GET | `patient-attachments` | نعم | قائمة مرفقات المريض |
| 35 | POST | `patient-attachments` | نعم | رفع مرفق جديد |
| 36 | GET | `medical-records/mine` | نعم | سجلاتي الطبية |
| 37 | GET | `medical-records/{record}` | نعم | تفاصيل سجل طبي |
| 38 | GET | `chat/doctors/{doctor}/messages` | نعم | محادثة مع دكتور |
| 39 | POST | `chat/doctors/{doctor}/messages` | نعم | إرسال رسالة |
| 40 | GET | `chat/unread-count` | نعم | عدد الرسائل غير المقروءة |
| 41 | GET | `offers/active` | لا | العروض النشطة |
| 42 | GET | `notifications` | نعم | قائمة الإشعارات |
| 43 | GET | `notifications/unread-count` | نعم | عدد غير المقروء |
| 44 | POST | `notifications/{id}/read` | نعم | تعليم إشعار كمقروء |
| 45 | POST | `notifications/read-all` | نعم | تعليم الكل كمقروء |

---

## 3) تفاصيل Auth (Register/Login/Profile...) — Controller: `Api\V1\Auth\AuthController`

### POST `auth/register`

| الحقل | النوع | القواعد |
|---|---|---|
| `name` | string | مطلوب، أقصى 255 حرف |
| `phone` | string | مطلوب، أقصى 50 حرف، **فريد** (`users.phone`) |
| `email` | string | اختياري، بريد صالح، أقصى 255 حرف، فريد لو اتبعت |
| `password` | string | مطلوب، مؤكّد (`password_confirmation`)، حسب قواعد Laravel `Password::defaults()` الافتراضية (8 أحرف على الأقل) |
| `date_of_birth` | date | اختياري، قبل اليوم |
| `gender` | string | اختياري، `male` أو `female` |

نجاح (`201 CREATED`): `{ user: {...}, token: "...", token_type: "Bearer" }`.
فشل تحقق شائع: `phone` مكرر → `422 VALIDATION_ERROR` مع `errors.phone`.

### POST `auth/login`

| الحقل | النوع | القواعد |
|---|---|---|
| `login` | string | مطلوب — هاتف أو إيميل (النظام بيحدد النوع تلقائيًا بـ `filter_var(...,FILTER_VALIDATE_EMAIL)`) |
| `password` | string | مطلوب |

بيانات خاطئة → `401 INVALID_CREDENTIALS`. 5 محاولات فاشلة خلال 60 ثانية (لنفس `login`+IP) →
`429 TOO_MANY_REQUESTS` مع `meta.retry_after` بالثواني.

### POST `auth/forgot-password` / `auth/reset-password`

بريد إلكتروني فقط (**لا يوجد OTP بالهاتف في هذه النسخة**). `forgot-password` يحتاج `email`
فقط؛ `reset-password` يحتاج `email` + `token` (من رابط الإيميل) + `password` مؤكّد.

### GET `auth/me` / PUT `auth/profile` / PUT `auth/password` / POST `auth/avatar` / DELETE `auth/account`

كل هذه محمية (`Authorization: Bearer {{token}}`)؛ التفاصيل الكاملة لكل حقل موجودة في وصف
كل Request داخل الـ Collection نفسها (Description tab في Postman).

**ملاحظة مهمة**: `PUT auth/profile` بيحدّث **البيانات الأساسية فقط** (الاسم/الهاتف/الإيميل/
العنوان/تاريخ الميلاد/الجنس) — **مش** الملف الطبي. الملف الطبي له مسار منفصل تمامًا:
`PUT patient-profile/medical` (قسم 5).

---

## 4) تفاصيل Settings/CMS — Controller: `Api\V1\SettingsController`

كل هذه المسارات **عامة** (بدون توكن) ما عدا `app-review` اللي بتقبل توكن اختياري (لو
اتبعت، الريفيو بيتربط بالمستخدم، لو معملهوش الريفيو بيتسجل anonymous).

| المسار | ملاحظات |
|---|---|
| `GET settings` | يرجع `app.min_version_android/ios`, `app.force_update`, `support.*`, `social_links`, `features.chat_enabled/video_call_enabled` (الأخيرة `false` دايمًا في هذه النسخة) |
| `GET settings/onboarding` | شرائح نشطة فقط، مرتّبة `sort_order` |
| `GET settings/pages/{type}` | `{type}` محصور في: `about`, `privacy_policy`, `privacy_terms` — أي قيمة تانية `404 NOT_FOUND` |
| `GET settings/faqs?category=&q=` | فلترة اختيارية بالتصنيف أو بحث نصي |
| `POST settings/contact` | `name`, `email`, `phone`, `subject`, `message` كلها **مطلوبة** |
| `POST settings/app-review` | `rating` (مطلوب 1-5), `comment` (اختياري، أقصى 2000), `platform` (اختياري: `ios`\|`android`\|`web`) |

---

## 5) ملاحظات عامة على النوع والتحقق (Validation) لكل التطبيق

- **التواريخ**: أي حقل `date` بيتوقع صيغة `YYYY-MM-DD` (مثال `2026-12-01`)، والأوقات بصيغة
  `H:i` (مثال `10:00`، 24 ساعة).
- **الأرقام (IDs)**: كل `_id` (مثل `doctor_id`, `clinic_profile_id`, `category_id`) لازم يكون
  رقم صحيح موجود فعلًا في قاعدة البيانات — استخدامه رقم غير موجود بيرجع إما `404` (route
  model binding) أو `422` (`exists:` rule في الـ FormRequest) حسب المسار.
- **الملفات (uploads)**: أي حقل `file`/`attachment`/`avatar` لازم يتبعت كـ
  `multipart/form-data` مش JSON — في Postman ده معمول تلقائيًا (Body → form-data → type: File).
  الحد الأقصى وأنواع الملفات المسموحة موضّحة في وصف كل Request.
- **Booleans**: بتتبعت كـ `true`/`false` (JSON boolean) في أجسام الـ JSON، أو `"1"`/`"0"`/
  `"true"`/`"false"` كنص في حالة `form-data` (Laravel's `boolean()` helper بيقبل الاتنين).
- **النصوص المترجمة (bilingual)**: أي حقل زي `name`/`title` في الاستجابة بيترجع **بلغة واحدة
  بس** حسب `Accept-Language` (مش object فيه `ar`/`en` مع بعض) — النظام بيختار الترجمة
  المناسبة تلقائيًا مع fallback للإنجليزية ثم العربية لو الترجمة المطلوبة مش موجودة.
- **الترقيم (Pagination)**: أي قائمة مرقّمة بترجع `meta.pagination` بالشكل: `current_page`,
  `per_page`, `total`, `last_page`. استخدم `?page=2` وهكذا للتنقل.
- **أكواد الأخطاء الشائعة اللي هتقابلها في هذه المجموعة تحديدًا**:

  | الكود | HTTP | امتى بيحصل هنا |
  |---|---|---|
  | `VALIDATION_ERROR` | 422 | بيانات ناقصة/غلط، أو قاعدة عمل زي "المعاد محجوز" أو "type=followup مرفوض" |
  | `MEDICAL_PROFILE_REQUIRED` | 428 | محاولة حجز قبل إكمال الملف الطبي |
  | `CONFLICT` | 409 | محاولة تقييم حجز اتقيّم قبل كده |
  | `FORBIDDEN` | 403 | محاولة الوصول لحجز/سجل طبي مش بتاعك |
  | `NOT_FOUND` | 404 | مورد غير موجود، أو دكتور غير نشط |
  | `UNAUTHENTICATED` | 401 | التوكن غايب/منتهي |
  | `INVALID_CREDENTIALS` | 401 | بيانات دخول غلط |
  | `TOO_MANY_REQUESTS` | 429 | محاولات دخول كتيرة |

  الجدول الكامل لكل الأكواد الممكنة موجود في [`00-api-response-format.md`](00-api-response-format.md).

---

## 6) قاعدة ثابتة تتكرر في أكتر من مسار

**حجز نوع `followup` (إعادة الكشف) غير متاح أبدًا من الموبايل.** أي محاولة تبعت
`"type": "followup"` في `POST bookings` هترجع `422 VALIDATION_ERROR`. الحجز ده بيتم من
لوحة تحكم الأدمن فقط. الموبايل بس بيعرض معلومة "الدكتور نصح بمتابعة" للقراءة فقط داخل تفاصيل
الحجز (`followup: {is_required, due_date, status}`) — بدون أي زر لحجزها.