# 📖 Mihrab API Documentation
## وثائق الـ API للمطورين

> **Base URL:** `https://mihrab-app.alwaysdata.net`  
> **Response Format:** JSON  
> **Encoding:** UTF-8

---

## 📑 جدول المحتويات
1. [القراء (Reciters)](#-القراء-reciters)
2. [التلاوات (Recitations)](#-التلاوات-recitations)
3. [السور (Surahs)](#-السور-surahs)
4. [المصاحف (Mushafs)](#-المصاحف-mushafs)
5. [الأذان (Adhans)](#-الأذان-adhans)
6. [إعدادات التطبيق (Settings)](#-إعدادات-التطبيق-settings)
7. [السلايدر (Slider)](#-السلايدر-slider)
8. [الإشعارات (Notifications)](#-الإشعارات-notifications)

---

## 🎙️ القراء (Reciters)

### جلب جميع القراء
**GET** `/api/reciters/read.php`

**الوصف:** يرجع قائمة بجميع القراء مع المصاحف الخاصة بكل قارئ.

**المتطلبات:** لا يوجد

**Response:**
```json
{
  "data": [
    {
      "id": "1",
      "name": "عبد الباسط عبد الصمد",
      "bio": "من أشهر قراء القرآن الكريم",
      "image_url": "https://mihrab-app.alwaysdata.net/uploads/reciters/abdulbasit.jpg",
      "category": "مشاهير",
      "mushafs": [
        {
          "id": "1",
          "name": "المصحف المرتل",
          "total_size_gb": "1.2",
          "is_series": "0"
        },
        {
          "id": "2",
          "name": "المصحف المجود",
          "total_size_gb": "2.5",
          "is_series": "0"
        }
      ]
    }
  ]
}
```

**الحقول:**
| الحقل | النوع | الوصف |
|-------|------|-------|
| `id` | string | المعرف الفريد للقارئ |
| `name` | string | اسم القارئ بالعربية |
| `bio` | string | نبذة عن القارئ |
| `image_url` | string | رابط صورة القارئ |
| `category` | string | تصنيف القارئ (مشاهير، شباب، الخ) |
| `mushafs` | array | قائمة المصاحف المتاحة للقارئ |

---

## 🎧 التلاوات (Recitations)

### جلب جميع التلاوات
**GET** `/api/recitations/read.php`

**الوصف:** يرجع جميع التلاوات مع إمكانية الفلترة.

**Query Parameters:**
| الباراميتر | النوع | مطلوب | الوصف |
|-----------|------|-------|-------|
| `reciter_id` | int | لا | فلترة حسب معرف القارئ |
| `mushaf_id` | int | لا | فلترة حسب معرف المصحف |

**مثال:** `/api/recitations/read.php?reciter_id=1&mushaf_id=2`

**Response:**
```json
{
  "data": [
    {
      "id": "1",
      "reciter_id": "1",
      "mushaf_id": "2",
      "surah_id": "1",
      "audio_url": "https://server.mp3quran.net/abd_basit/001.mp3",
      "reciter_name": "عبد الباسط عبد الصمد",
      "mushaf_name": "المصحف المرتل",
      "created_at": "2024-01-15 10:30:00"
    }
  ]
}
```

---

### جلب تلاوات قارئ معين
**GET** `/api/recitations/read_by_reciter.php`

**الوصف:** يرجع جميع تلاوات قارئ محدد.

**Query Parameters:**
| الباراميتر | النوع | مطلوب | الوصف |
|-----------|------|-------|-------|
| `reciter_id` | int | ✅ نعم | معرف القارئ |

**مثال:** `/api/recitations/read_by_reciter.php?reciter_id=1`

**Response:**
```json
{
  "data": [
    {
      "id": "1",
      "reciter_id": "1",
      "mushaf_id": "2",
      "surah_id": "1",
      "audio_url": "https://server.mp3quran.net/abd_basit/001.mp3"
    }
  ]
}
```

**رسالة الخطأ (400):**
```json
{
  "message": "reciter_id required"
}
```

---

### جلب تلاوة واحدة
**GET** `/api/recitations/read_single.php`

**الوصف:** يرجع بيانات تلاوة محددة بالمعرف.

**Query Parameters:**
| الباراميتر | النوع | مطلوب | الوصف |
|-----------|------|-------|-------|
| `id` | int | ✅ نعم | معرف التلاوة |

**مثال:** `/api/recitations/read_single.php?id=5`

**Response (200):**
```json
{
  "id": "5",
  "reciter_id": "1",
  "mushaf_id": "2",
  "surah_id": "5",
  "audio_url": "https://server.mp3quran.net/abd_basit/005.mp3",
  "reciter_name": "عبد الباسط عبد الصمد"
}
```

**Response (404):**
```json
{
  "message": "Recitation not found"
}
```

---

## 📖 السور (Surahs)

### جلب جميع السور
**GET** `/api/surahs/read.php`

**الوصف:** يرجع قائمة السور الـ 114 للقرآن الكريم.

**المتطلبات:** لا يوجد

**Response:**
```json
{
  "data": [
    {
      "id": 1,
      "name": "الفاتحة",
      "name_english": "Al-Fatihah",
      "verses": 7
    },
    {
      "id": 2,
      "name": "البقرة",
      "name_english": "Al-Baqarah",
      "verses": 286
    }
  ]
}
```

**الحقول:**
| الحقل | النوع | الوصف |
|-------|------|-------|
| `id` | int | رقم السورة (1-114) |
| `name` | string | اسم السورة بالعربية |
| `name_english` | string | اسم السورة بالإنجليزية |
| `verses` | int | عدد آيات السورة |

---

## 📚 المصاحف (Mushafs)

### جلب جميع المصاحف
**GET** `/api/mushafs/read_all.php`

**الوصف:** يرجع قائمة بجميع المصاحف مع أسماء القراء.

**Response:**
```json
{
  "data": [
    {
      "id": "1",
      "name": "المصحف المرتل - رواية حفص",
      "reciter_id": "1",
      "reciter_name": "عبد الباسط عبد الصمد",
      "total_size_gb": "1.2"
    }
  ]
}
```

---

### جلب مصاحف قارئ معين
**GET** `/api/mushafs/read_by_reciter.php`

**الوصف:** يرجع المصاحف الخاصة بقارئ محدد.

**Query Parameters:**
| الباراميتر | النوع | مطلوب | الوصف |
|-----------|------|-------|-------|
| `reciter_id` | int | ✅ نعم | معرف القارئ |
| `parent_id` | int | لا | معرف المصحف الأب (للمجلدات الفرعية) |
| `show_all` | bool | لا | إظهار جميع المصاحف بما فيها الفرعية |

**مثال:** `/api/mushafs/read_by_reciter.php?reciter_id=1`

**Response:**
```json
{
  "data": [
    {
      "id": "1",
      "name": "المصحف المرتل",
      "reciter_id": "1",
      "is_series": "0",
      "total_size_gb": "1.2",
      "total_size_mb": "1228"
    }
  ]
}
```

**الحقول:**
| الحقل | النوع | الوصف |
|-------|------|-------|
| `id` | string | معرف المصحف |
| `name` | string | اسم المصحف |
| `reciter_id` | string | معرف القارئ |
| `is_series` | string | هل هو سلسلة (1) أم مصحف عادي (0) |
| `total_size_gb` | string | الحجم الكلي بالجيجابايت |
| `total_size_mb` | string | الحجم الكلي بالميجابايت |

---

## 🕌 الأذان (Adhans)

### جلب جميع الأذانات
**GET** `/api/adhans/read.php`

**الوصف:** يرجع قائمة بجميع ملفات الأذان المتاحة.

**المتطلبات:** لا يوجد

**Response:**
```json
{
  "data": [
    {
      "id": "1",
      "reciter_name": "عبد الباسط عبد الصمد",
      "audio_url": "https://mihrab-app.alwaysdata.net/uploads/adhans/abdulbasit.mp3"
    },
    {
      "id": "2",
      "reciter_name": "مشاري العفاسي",
      "audio_url": "https://mihrab-app.alwaysdata.net/uploads/adhans/alafasy.mp3"
    }
  ]
}
```

**الحقول:**
| الحقل | النوع | الوصف |
|-------|------|-------|
| `id` | string | معرف الأذان |
| `reciter_name` | string | اسم المؤذن |
| `audio_url` | string | رابط ملف الأذان الصوتي |

---

## ⚙️ إعدادات التطبيق (Settings)

### جلب إعدادات التطبيق
**GET** `/api/settings/read.php`

**الوصف:** يرجع إعدادات التطبيق العامة.

**المتطلبات:** لا يوجد

**Response:**
```json
{
  "data": [
    {
      "key": "app_version",
      "value": "1.5.0",
      "updated_at": "2024-01-15 10:30:00"
    },
    {
      "key": "maintenance_mode",
      "value": "false",
      "updated_at": "2024-01-10 08:00:00"
    }
  ]
}
```

**الحقول:**
| الحقل | النوع | الوصف |
|-------|------|-------|
| `key` | string | مفتاح الإعداد |
| `value` | string | قيمة الإعداد |
| `updated_at` | string | تاريخ آخر تحديث |

---

## 🖼️ السلايدر (Slider)

### جلب جميع السلايدر
**GET** `/api/slider/read.php`

**الوصف:** يرجع صور السلايدر للشاشة الرئيسية.

**المتطلبات:** لا يوجد

**Response:**
```json
{
  "data": [
    {
      "id": "1",
      "title": "رمضان كريم",
      "image_url": "https://mihrab-app.alwaysdata.net/uploads/slider/ramadan.jpg",
      "link_url": "https://example.com/ramadan",
      "created_at": "2024-01-15 10:30:00"
    }
  ]
}
```

**الحقول:**
| الحقل | النوع | الوصف |
|-------|------|-------|
| `id` | string | معرف السلايدر |
| `title` | string | عنوان السلايدر |
| `image_url` | string | رابط الصورة |
| `link_url` | string | الرابط عند الضغط |
| `created_at` | string | تاريخ الإنشاء |

---

### جلب سلايدر واحد
**GET** `/api/slider/read_single.php`

**الوصف:** يرجع بيانات سلايدر محدد.

**Query Parameters:**
| الباراميتر | النوع | مطلوب | الوصف |
|-----------|------|-------|-------|
| `id` | int | ✅ نعم | معرف السلايدر |

**مثال:** `/api/slider/read_single.php?id=1`

**Response (200):**
```json
{
  "id": "1",
  "title": "رمضان كريم",
  "image_url": "https://mihrab-app.alwaysdata.net/uploads/slider/ramadan.jpg",
  "link_url": "https://example.com/ramadan",
  "created_at": "2024-01-15 10:30:00"
}
```

**Response (404):**
```json
{
  "message": "Slider not found"
}
```

---

## 🔔 الإشعارات (Notifications)

### جلب جميع الإشعارات
**GET** `/api/notifications/read.php`

**الوصف:** يرجع قائمة الإشعارات.

**المتطلبات:** لا يوجد

**Response:**
```json
{
  "data": [
    {
      "id": "1",
      "title": "تحديث جديد",
      "message": "تم إضافة قارئ جديد للتطبيق",
      "type": "general",
      "created_at": "2024-01-15 10:30:00"
    }
  ]
}
```

**الحقول:**
| الحقل | النوع | الوصف |
|-------|------|-------|
| `id` | string | معرف الإشعار |
| `title` | string | عنوان الإشعار |
| `message` | string | نص الإشعار |
| `type` | string | نوع الإشعار (general, update, etc.) |
| `created_at` | string | تاريخ الإنشاء |

---

## 🔧 ملاحظات عامة

### Headers المطلوبة
جميع الـ endpoints تدعم:
```
Content-Type: application/json
```

### CORS
الـ API يدعم CORS ويسمح بالوصول من أي domain:
```
Access-Control-Allow-Origin: *
```

### رموز HTTP المستخدمة
| الكود | المعنى |
|-------|--------|
| `200` | Success - تم بنجاح |
| `400` | Bad Request - باراميتر مفقود أو خاطئ |
| `404` | Not Found - العنصر المطلوب غير موجود |

### بنية Response العامة
جميع endpoints التي ترجع قوائم تستخدم البنية التالية:
```json
{
  "data": [...]
}
```

عند عدم وجود بيانات:
```json
{
  "message": "No items found",
  "data": []
}
```

---

## 📞 للتواصل
في حالة وجود أي استفسارات، تواصل مع فريق التطوير.

**آخر تحديث:** 2026-01-17