# دليل نقاط الـ API والـ Endpoints — 7 Tech

> **تاريخ التحديث**: أغسطس 2026  
> **السيرفر المحلي**: `http://localhost:8000` *(أو عبر الشبكة: `http://192.168.1.146:8000`)*  
> **Base API URL**: `http://localhost:8000/api/v1`  
> **نوع المصادقة**: `Authorization: Bearer <API_TOKEN>`  
> **الترويسة المطلوبة (Header)**: `Accept: application/json`

---

## 📌 جدول المحتويات
1. [المصادقة وإدارة الـ Tokens](#1-المصادقة-وإدارة-الـ-tokens-auth)
2. [نقاط الإرسال العامة من الواجهة الأمامية (Public Actions & Forms)](#2-نقاط-الإرسال-العامة-من-الواجهة-الأمامية-public-actions--forms)
3. [المحتوى العام وكتالوج الأعمال (Public Content & Catalog)](#3-المحتوى-العام-وكتالوج-الأعمال-public-content--catalog)
4. [الإدارة والعمليات ولوحة التحكم (Admin & Operations)](#4-الإدارة-والعمليات-ولوحة-التحكم-admin--operations)
5. [معاملات الفلترة والبحث والترقيم (Pagination & Filtering)](#5-معاملات-الفلترة-والبحث-والترقيم-pagination--filtering)

---

## 1. المصادقة وإدارة الـ Tokens (Auth)

| الوظيفة | Method | Endpoint URL | الترويسة / الصلاحية | ملاحظات |
|---|:---:|---|:---:|---|
| **فهرس الـ API العام** | `GET` | `/api/v1` | عام (بدون Token) | معلومات الإصدار والموارد المتاحة |
| **مواصفة OpenAPI 3.1** | `GET` | `/api/v1/openapi` | عام (بدون Token) | مستند OpenAPI بصيغة JSON |
| **تسجيل الدخول وإصدار Token** | `POST` | `/api/v1/auth/token` | عام | يتطلب Body: `email`, `password`, `name` |
| **بيانات المستخدم الحالي** | `GET` | `/api/v1/auth/me` | Bearer Token | جلب بيانات المستخدم وصلاحياته |
| **قائمة توكنات الحساب** | `GET` | `/api/v1/auth/tokens` | Bearer Token | استعراض التوكنات النشطة |
| **تفاصيل التوكن الحالي** | `GET` | `/api/v1/auth/token/current` | Bearer Token | جلب معلومات التوكن المستخدم حالياً |
| **إلغاء التوكن الحالي (Logout)** | `DELETE` | `/api/v1/auth/token/current` | Bearer Token | إلغاء وحذف التوكن الحالي |
| **إلغاء توكن محدد** | `DELETE` | `/api/v1/auth/tokens/{token_uuid}` | Bearer Token | إلغاء جلسة جهاز آخر |
| **إلغاء كافة توكنات الحساب** | `DELETE` | `/api/v1/auth/tokens` | Bearer Token | تسجيل الخروج من كل الأجهزة |

### 💡 مثال على تسجيل الدخول (`POST /api/v1/auth/token`):
```json
// Request Body
{
  "email": "admin@7tech.com",
  "password": "your_secure_password",
  "name": "Frontend Application"
}

// Response (200 OK)
{
  "data": {
    "token": "1|qX8zJ... (Bearer Token)",
    "user": {
      "id": "usr_...",
      "name": "Admin User",
      "email": "admin@7tech.com",
      "roles": ["Administrator"]
    }
  }
}
```

---

## 2. نقاط الإرسال العامة من الواجهة الأمامية (Public Actions & Forms)

هذه الـ Endpoints مخصصة لاستقبال طلبات الزوار من الواجهة الأمامية للموقع (Angular / Next.js / Mobile Apps):

| الوظيفة | Method | Endpoint URL | الترويسة / الصلاحية | الحقول المطلوبة (Payload) |
|---|:---:|---|:---:|---|
| **طلب عرض سعر (Quote Request)** | `POST` | `/quote` | عام | `name`, `email`, `phone`, `service_id`, `budget_range`, `message` |
| **حجز استشارة / موعد (Booking)** | `POST` | `/book` | عام | `name`, `email`, `phone`, `meeting_type_id`, `preferred_time`, `notes` |
| **التقديم على وظيفة (Job Application)** | `POST` | `/careers/{job_id}/applications` | عام (Multipart) | `name`, `email`, `phone`, `resume_file`, `cover_letter`, `portfolio_url` |
| **عرض الصور المخزنة** | `GET` | `/content-images/{media_uuid}` | عام | جلب الصورة مباشرة عبر المعرف |
| **فحص جاهزية النظام (Health)** | `GET` | `/health/ready` | عام | التأكد من عمل السيرفر وقاعدة البيانات |

---

## 3. المحتوى العام وكتالوج الأعمال (Public Content & Catalog)

جميع هذه الموارد تُجلب عبر الـ API الموحد: `GET /api/v1/resources/{resource_name}`  
وتدعم الفلترة، الترتيب، والترقيم التلقائي:

### 🔹 الخدمات والحلول (Catalog & Services)
* **قائمة الخدمات**: `GET /api/v1/resources/services`
* **تفاصيل خدمة بالـ Slug أو ID**: `GET /api/v1/resources/services/{slug_or_id}`
* **تصنيفات الخدمات**: `GET /api/v1/resources/service-categories`
* **القوالب والحلول البرمجية**: `GET /api/v1/resources/templates`
* **التقنيات المستخدمة**: `GET /api/v1/resources/technologies`

### 🔹 سابقة الأعمال والشركاء (Portfolio & Partners)
* **المشاريع وسابقة الأعمال**: `GET /api/v1/resources/projects`
* **تفاصيل مشروع محدد**: `GET /api/v1/resources/projects/{id}`
* **قائمة العملاء**: `GET /api/v1/resources/clients`
* **الشركاء والتحالفات**: `GET /api/v1/resources/partners`

### 🔹 المقالات والوظائف (Blog & Careers)
* **المقالات المنشورة في المدونة**: `GET /api/v1/resources/posts`
* **تفاصيل مقال بالـ Slug**: `GET /api/v1/resources/posts/{slug}`
* **الوظائف الشاغرة**: `GET /api/v1/resources/jobs`
* **تفاصيل وظيفة محددة**: `GET /api/v1/resources/jobs/{id}`

### 🔹 باقات الأسعار (Pricing & Packages)
* **باقات الخدمات والأسعار**: `GET /api/v1/resources/packages`
* **قوائم الأسعار الرسمية**: `GET /api/v1/resources/price-lists`
* **العملات المدعومة**: `GET /api/v1/resources/currencies`

### 🔹 هوية الشركة ومحتوى الأقسام (Company, Home, Menus & Footer)
* **بيانات وهوية الشركة**: `GET /api/v1/resources/company-profiles`
* **محتوى الصفحة الرئيسية**: `GET /api/v1/resources/home-pages`
* **أقسام الصفحة الرئيسية**: `GET /api/v1/resources/home-page-sections`
* **إعدادات شريط القائمة العلوي**: `GET /api/v1/resources/menu-bar-settings`
* **روابط شريط القائمة**: `GET /api/v1/resources/menu-bar-links`
* **إعدادات الفوتر (التذييل)**: `GET /api/v1/resources/footer-settings`
* **روابط الفوتر**: `GET /api/v1/resources/footer-links`

---

## 4. الإدارة والعمليات ولوحة التحكم (Admin & Operations)

*(تتطلب Bearer Token مع صلاحيات الإدارة)*

| المورد / الوظيفة | Method | Endpoint URL | الصلاحية المطلوبة |
|---|:---:|---|:---:|
| **لوحة تحكم التحليلات (Dashboard)** | `GET` | `/api/v1/dashboard?from=YYYY-MM-DD&to=YYYY-MM-DD` | `analytics.view` |
| **إدارة المستخدمين** | `GET` | `/api/v1/resources/users` | `users.view` |
| **الأدوار والصلاحيات** | `GET` | `/api/v1/resources/roles` | `roles.view` |
| **الصلاحيات المتاحة** | `GET` | `/api/v1/resources/permissions` | `permissions.view` |
| **طلبات عروض الأسعار (Quotations)** | `GET` | `/api/v1/resources/quotations` | `quotations.view` |
| **العملاء المحتملين (Leads)** | `GET` | `/api/v1/resources/leads` | `crm.view` |
| **جهات الاتصال (Contacts)** | `GET` | `/api/v1/resources/contacts` | `crm.view` |
| **الاجتماعات المجدولة (Meetings)** | `GET` | `/api/v1/resources/meetings` | `meetings.view` |
| **أنواع الاجتماعات (Meeting Types)** | `GET` | `/api/v1/resources/meeting-types` | `meetings.view` |
| **مكتبة الوسائط والملفات (Media)** | `GET` | `/api/v1/resources/media` | `media.view` |
| **وكلاء الذكاء الاصطناعي (AI Agents)** | `GET` | `/api/v1/resources/ai-agents` | `ai.view` |
| **اتصالات التكامل (Integrations)** | `GET` | `/api/v1/resources/integration-connections` | `integrations.view` |
| **بيانات SEO الوصفية** | `GET` | `/api/v1/resources/seo-metadata` | `seo.view` |
| **إعدادات النظام العامة** | `GET` | `/api/v1/resources/settings` | `settings.view` |

---

## 5. معاملات الفلترة والبحث والترقيم (Pagination & Filtering)

يمكن تمرير المعاملات التالية عبر الـ Query String مع أي مورد من موارد `resources`:

| المعامل (Parameter) | الوصف | مثال |
|---|---|---|
| `page` | رقم الصفحة (الافتراضي: 1) | `?page=2` |
| `per_page` | عدد العناصر في الصفحة (الافتراضي: 25، الحد الأقصى: 100) | `?per_page=50` |
| `q` | بحث نصي حر في الحقول المدعومة (الاسم، العنوان، الوصف) | `?q=تطبيقات` |
| `sort` | حقل الترتيب (مثل: `created_at`, `display_order`, `name`) | `?sort=display_order` |
| `direction` | اتجاه الترتيب (`asc` أو `desc`) | `?direction=asc` |
| `filter[field]` | فلترة مباشرة حسب حقل معين | `?filter[status]=published` |

### 💡 مثال كامل على الاستعلام:
```http
GET /api/v1/resources/services?filter[status]=published&sort=display_order&direction=asc&per_page=10 HTTP/1.1
Host: localhost:8000
Accept: application/json
```