site_backend/API_DOCS_FA.md

<div dir="rtl" lang="fa">

# مستندات API (Zoneco ORG)

این سند نحوهٔ کارکرد APIهای بک‌اند پروژه Zoneco ORG را به زبان فارسی توضیح می‌دهد.

---

## وضعیت تست‌ها

```
Ran 24 tests — OK (0 failures)
```

| تعداد تست | گروه |
|-----------|------|
| ۶ تست | Contact Us |
| ۱۱ تست | Compositions |
| ۷ تست | Campaigns |

اجرای تست‌ها:

```bash
cd backend
python manage.py test api -v 2
```

---

## اطلاعات پایه

| مقدار | مورد |
|--------|------|
| `{{base_url}}` | آدرس پایه |
| `/api/` | پیشوند API |
| JSON | فرمت پاسخ |
| ۲۰ آیتم در هر صفحه | صفحه‌بندی |
| `/admin/` | پنل ادمین |

### متغیر Postman

در فایل Postman از متغیر `{{base_url}}` استفاده شده است.  
مقدار آن را مطابق محیط اجرا (لوکال، سرور تست یا پروداکشن) تنظیم کنید.

**نمونهٔ آدرس کامل یک endpoint:**

```
{{base_url}}/api/contact-us/
```

---

## سطح دسترسی

| دسترسی | عملیات |
|--------|--------|
| عمومی — بدون نیاز به ورود | لیست و جزئیات (متد `GET`) |
| عمومی — بدون نیاز به ورود | ایجاد (متد `POST`) |
| فقط ادمین — نیاز به احراز هویت | ویرایش و حذف (متدهای `PUT`، `PATCH`، `DELETE`) |

برای درخواست‌های ادمین در Postman می‌توانید از **Basic Auth** با نام کاربری و رمز ادمین استفاده کنید.

---

## ۱. تماس با ما (Contact Us)

**مسیر پایه:**

```
/api/contact-us/
```

### فیلدها

| توضیح | الزامی | نوع | فیلد |
|-------|--------|-----|------|
| نام و نام خانوادگی | بله | string | `name` |
| ایمیل یا شماره تماس | بله | string | `email_or_phone` |
| متن پیام | بله | string | `description` |
| دسته‌بندی | بله | string | `category` |

**مقادیر مجاز برای `category`:**

- همکاری
- فروش
- پشتیبانی
- درخواست مشاور
- سایر

---

### دریافت لیست تماس‌ها

```
GET {{base_url}}/api/contact-us/
```

**پاسخ نمونه:**

```json
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "احمد محمدی",
      "email_or_phone": "ahmad@example.com",
      "description": "سلام، سوالی دارم.",
      "category": "پشتیبانی",
      "created_at": "2025-12-17T12:00:00Z",
      "updated_at": "2025-12-17T12:00:00Z"
    }
  ]
}
```

---

### دریافت یک تماس

```
GET {{base_url}}/api/contact-us/{id}/
```

---

### ثبت تماس جدید

```
POST {{base_url}}/api/contact-us/
Content-Type: application/json
```

**بدنه درخواست:**

```json
{
  "name": "احمد محمدی",
  "email_or_phone": "09121234567",
  "description": "می‌خواهم در مورد محصولات اطلاعات بگیرم.",
  "category": "فروش"
}
```

**کد پاسخ:** `201 Created`

---

### فیلتر بر اساس دسته‌بندی

```
GET {{base_url}}/api/contact-us/by_category/?category=پشتیبانی
```

| توضیح | الزامی | پارامتر |
|-------|--------|---------|
| یکی از دسته‌های مجاز | بله | `category` |

اگر پارامتر `category` ارسال نشود، خطای `400` برمی‌گردد.

---

### ویرایش و حذف (ادمین)

```
PUT    {{base_url}}/api/contact-us/{id}/
PATCH  {{base_url}}/api/contact-us/{id}/
DELETE {{base_url}}/api/contact-us/{id}/
```

نیاز به احراز هویت ادمین دارد.

---

## ۲. ترکیبات (Compositions)

**مسیر پایه:**

```
/api/compositions/
```

هر ترکیب می‌تواند **چند تصویر** داشته باشد.  
یکی از تصاویر با فیلد `is_main: true` به‌عنوان **تصویر اصلی** مشخص می‌شود.

### فیلدها

| توضیح | الزامی | نوع | فیلد |
|-------|--------|-----|------|
| نام ترکیب | بله | string | `name` |
| توضیحات | بله | string | `description` |
| یک یا چند فایل تصویر (فقط در ایجاد/ویرایش) | خیر | file[] | `uploaded_images` |
| ایندکس تصویر اصلی (شمارش از ۰) | خیر | integer | `main_image_index` |

### محدودیت تصاویر

- فرمت‌های مجاز: JPEG، PNG، WebP، GIF
- حداکثر حجم هر فایل: **۵ مگابایت**
- مسیر ذخیره: `media/compositions/`

---

### دریافت لیست ترکیبات

```
GET {{base_url}}/api/compositions/
```

---

### دریافت یک ترکیب

```
GET {{base_url}}/api/compositions/{id}/
```

**پاسخ نمونه:**

```json
{
  "id": 1,
  "name": "ترکیب A",
  "description": "توضیحات ترکیب",
  "image": null,
  "image_url": null,
  "images": [
    {
      "id": 2,
      "image": "/media/compositions/img2.jpg",
      "image_url": "{{base_url}}/media/compositions/img2.jpg",
      "is_main": true,
      "created_at": "2025-12-17T12:00:00Z"
    },
    {
      "id": 1,
      "image": "/media/compositions/img1.jpg",
      "image_url": "{{base_url}}/media/compositions/img1.jpg",
      "is_main": false,
      "created_at": "2025-12-17T11:00:00Z"
    }
  ],
  "main_image": {
    "id": 2,
    "image_url": "{{base_url}}/media/compositions/img2.jpg",
    "is_main": true,
    "created_at": "2025-12-17T12:00:00Z"
  },
  "created_at": "2025-12-17T10:00:00Z",
  "updated_at": "2025-12-17T12:00:00Z"
}
```

---

### فیلتر بر اساس تاریخ ایجاد

```
GET {{base_url}}/api/compositions/by-created-at/?from=2026-06-01T00:00:00Z&to=2026-06-30T23:59:59Z
```

| توضیح | الزامی | پارامتر |
|-------|--------|---------|
| برگشت ترکیب‌هایی که `created_at >= from` | حداقل یکی | `from` |
| برگشت ترکیب‌هایی که `created_at <= to` | حداقل یکی | `to` |

فرمت تاریخ: ISO 8601 — مثال: `2026-06-01T00:00:00Z`

اگر هیچ پارامتری ارسال نشود، خطای `400` برمی‌گردد.

---

### ایجاد ترکیب (بدون تصویر)

```
POST {{base_url}}/api/compositions/
Content-Type: application/json
```

```json
{
  "name": "ترکیب تست",
  "description": "توضیحات ترکیب"
}
```

---

### ایجاد ترکیب با چند تصویر

```
POST {{base_url}}/api/compositions/
Content-Type: multipart/form-data
```

| مقدار نمونه | نوع | فیلد |
|-------------|-----|------|
| ترکیب A | text | `name` |
| توضیحات | text | `description` |
| image1.jpg | file | `uploaded_images` |
| image2.jpg | file | `uploaded_images` |
| 1 | text | `main_image_index` |

**نکته:** فیلد `uploaded_images` را برای هر تصویر یک‌بار تکرار کنید.

**نکته:** اگر `main_image_index` ارسال نشود، **اولین تصویر** به‌عنوان تصویر اصلی انتخاب می‌شود.

---

### افزودن تصویر به ترکیب موجود (ادمین)

```
POST {{base_url}}/api/compositions/{id}/add-images/
Content-Type: multipart/form-data
```

| نوع | فیلد |
|-----|------|
| file (یک یا چند فایل) | `uploaded_images` |
| text (اختیاری) | `main_image_index` |

---

### تنظیم تصویر اصلی (ادمین)

```
POST {{base_url}}/api/compositions/{id}/set-main-image/
Content-Type: application/json
```

```json
{
  "image_id": 3
}
```

---

### حذف یک تصویر (ادمین)

```
DELETE {{base_url}}/api/compositions/{id}/images/{image_id}/
```

**کد پاسخ:** `204 No Content`

---

### ویرایش و حذف ترکیب (ادمین)

```
PUT    {{base_url}}/api/compositions/{id}/
PATCH  {{base_url}}/api/compositions/{id}/
DELETE {{base_url}}/api/compositions/{id}/
```

---

## ۳. کمپین‌ها (Campaigns)

**مسیر پایه:**

```
/api/campaigns/
```

### فیلدها

| توضیح | الزامی | نوع | فیلد |
|-------|--------|-----|------|
| نام کمپین | بله | string | `name` |
| توضیحات | بله | string | `description` |
| زمان شروع (ISO 8601) | بله | datetime | `start_time` |
| زمان پایان (باید بعد از `start_time` باشد) | بله | datetime | `end_time` |
| تصویر کمپین | خیر | file | `image` |

### فیلدهای محاسباتی (فقط خواندنی)

| توضیح | فیلد |
|-------|------|
| آیا کمپین الان فعال است | `is_active` |
| آیا کمپین هنوز شروع نشده | `is_upcoming` |
| آیا کمپین تمام شده | `is_ended` |

---

### دریافت لیست کمپین‌ها

```
GET {{base_url}}/api/campaigns/
```

---

### دریافت یک کمپین

```
GET {{base_url}}/api/campaigns/{id}/
```

---

### ایجاد کمپین

```
POST {{base_url}}/api/campaigns/
Content-Type: application/json
```

```json
{
  "name": "کمپین نوروز",
  "description": "تخفیف ویژه نوروز",
  "start_time": "2026-03-01T00:00:00Z",
  "end_time": "2026-03-31T23:59:59Z"
}
```

---

### کمپین‌های فعال

```
GET {{base_url}}/api/campaigns/active/
```

کمپین‌هایی که زمان فعلی بین `start_time` و `end_time` قرار دارد.

---

### کمپین‌های آینده

```
GET {{base_url}}/api/campaigns/upcoming/
```

کمپین‌هایی که هنوز شروع نشده‌اند.

---

### کمپین‌های پایان‌یافته

```
GET {{base_url}}/api/campaigns/ended/
```

---

### ویرایش و حذف (ادمین)

```
PUT    {{base_url}}/api/campaigns/{id}/
PATCH  {{base_url}}/api/campaigns/{id}/
DELETE {{base_url}}/api/campaigns/{id}/
```

---

## کدهای وضعیت HTTP

| معنی | کد |
|------|-----|
| موفق | `200` |
| ایجاد شد | `201` |
| حذف شد (بدون بدنه) | `204` |
| داده نامعتبر | `400` |
| دسترسی ندارید | `403` |
| یافت نشد | `404` |

---

## فایل Postman

مجموعه Postman در مسیر زیر قرار دارد:

```
backend/Zoneco_ORG_API.postman_collection.json
```

### نحوه import

1. Postman را باز کنید
2. گزینه **Import** را بزنید
3. فایل `Zoneco_ORG_API.postman_collection.json` را انتخاب کنید
4. متغیر `{{base_url}}` را مطابق محیط خود تنظیم کنید
5. برای درخواست‌های ادمین، در تب **Authorization** گزینه **Basic Auth** را فعال کنید

---

## خلاصه endpointها

| دسترسی | Endpoint | Method | # |
|--------|----------|--------|---|
| عمومی | `/api/contact-us/` | GET | 1 |
| عمومی | `/api/contact-us/` | POST | 2 |
| عمومی | `/api/contact-us/{id}/` | GET | 3 |
| عمومی | `/api/contact-us/by_category/?category=...` | GET | 4 |
| ادمین | `/api/contact-us/{id}/` | PUT/PATCH/DELETE | 5 |
| عمومی | `/api/compositions/` | GET | 6 |
| عمومی | `/api/compositions/` | POST | 7 |
| عمومی | `/api/compositions/{id}/` | GET | 8 |
| عمومی | `/api/compositions/by-created-at/?from=...&to=...` | GET | 9 |
| ادمین | `/api/compositions/{id}/add-images/` | POST | 10 |
| ادمین | `/api/compositions/{id}/set-main-image/` | POST | 11 |
| ادمین | `/api/compositions/{id}/images/{image_id}/` | DELETE | 12 |
| ادمین | `/api/compositions/{id}/` | PUT/PATCH/DELETE | 13 |
| عمومی | `/api/campaigns/` | GET | 14 |
| عمومی | `/api/campaigns/` | POST | 15 |
| عمومی | `/api/campaigns/{id}/` | GET | 16 |
| عمومی | `/api/campaigns/active/` | GET | 17 |
| عمومی | `/api/campaigns/upcoming/` | GET | 18 |
| عمومی | `/api/campaigns/ended/` | GET | 19 |
| ادمین | `/api/campaigns/{id}/` | PUT/PATCH/DELETE | 20 |

> **توجه:** در Postman قبل از هر مسیر، مقدار `{{base_url}}` را قرار دهید.  
> مثال: `{{base_url}}/api/campaigns/active/`

</div>