site_backend/API_DOCS_FA.md

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

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

---

وضعیت تست‌ها

Ran 24 tests — OK (0 failures)

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

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

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/

پاسخ نمونه:

{
  "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

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

{
  "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}/

پاسخ نمونه:

{
  "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

{
  "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

{
  "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

{
  "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/