site_backend/README.md

Zoneco ORG Backend API

A Django REST Framework backend for Zoneco ORG with PostgreSQL database.

---

Test Status

Ran 24 tests in ~12s — OK (0 failures)

Group	Tests	Status
Contact Us	6	✅ All pass
Compositions	11	✅ All pass
Campaigns	7	✅ All pass

Run tests at any time:

cd backend
python manage.py test api -v 2

---

Features

• Contact Us API — Contact form submissions with category filter
• Composition API — Multi-image upload, main image flag, date-range filter
• Campaign API — Campaigns with active / upcoming / ended filters
• Admin Panel — Full Django admin at /admin/
• Image Upload — JPEG, PNG, WebP, GIF, max 5 MB, stored in media/
• CORS Enabled — Configured for frontend integration
• Pagination — 20 items per page

---

Quick Start

1. Install dependencies

pip install -r requirements.txt

2. Create PostgreSQL database

CREATE DATABASE "Zoneco_ORG";

3. Apply migrations

python manage.py migrate

4. Run development server

python manage.py runserver

API available at {{base_url}}/api/

---

Admin Credentials

Field	Value
URL	{{base_url}}/admin/
Username	Zoneco_@1405
Password	Fun_@_zone2026

---

API Endpoints

Authentication

Action	Access
GET (list, retrieve, custom filters)	Public — no login required
POST (create)	Public — no login required
PUT / PATCH / DELETE	Admin only — Basic Auth required

---

Contact Us — /api/contact-us/

Method	Endpoint	Access	Description
GET	/api/contact-us/	Public	List all submissions
POST	/api/contact-us/	Public	Submit a contact form
GET	/api/contact-us/{id}/	Public	Get one submission
GET	/api/contact-us/by_category/?category=...	Public	Filter by category
PATCH	/api/contact-us/{id}/	Admin	Partial update
PUT	/api/contact-us/{id}/	Admin	Full update
DELETE	/api/contact-us/{id}/	Admin	Delete

Category choices: همکاری · فروش · پشتیبانی · درخواست مشاور · سایر

Fields:

Field	Type	Required
name	string	Yes
email_or_phone	string	Yes
description	string	Yes
category	string	Yes

---

Compositions — /api/compositions/

Each composition can have multiple images. One image can be flagged as the main image (is_main: true).

Method	Endpoint	Access	Description
GET	/api/compositions/	Public	List all compositions
POST	/api/compositions/	Public	Create composition (with optional images)
GET	/api/compositions/{id}/	Public	Get one composition
GET	/api/compositions/by-created-at/?from=...&to=...	Public	Filter by creation date range
POST	/api/compositions/{id}/add-images/	Admin	Add images to existing composition
POST	/api/compositions/{id}/set-main-image/	Admin	Set main image
DELETE	/api/compositions/{id}/images/{image_id}/	Admin	Delete a single image
PATCH	/api/compositions/{id}/	Admin	Partial update
PUT	/api/compositions/{id}/	Admin	Full update
DELETE	/api/compositions/{id}/	Admin	Delete composition

Fields:

Field	Type	Required	Notes
name	string	Yes
description	string	Yes
uploaded_images	file[]	No	One or more image files (multipart)
main_image_index	integer	No	0-based index of main image in uploaded_images. Defaults to 0.

Image constraints: JPEG, PNG, WebP, GIF — max 5 MB each — stored at media/compositions/

by-created-at query params:

Param	Required	Format
from	At least one	ISO 8601 e.g. 2026-06-01T00:00:00Z
to	At least one	ISO 8601 e.g. 2026-06-30T23:59:59Z

---

Campaigns — /api/campaigns/

Method	Endpoint	Access	Description
GET	/api/campaigns/	Public	List all campaigns
POST	/api/campaigns/	Public	Create campaign
GET	/api/campaigns/{id}/	Public	Get one campaign
GET	/api/campaigns/active/	Public	Currently active campaigns
GET	/api/campaigns/upcoming/	Public	Not started yet
GET	/api/campaigns/ended/	Public	Already finished
PATCH	/api/campaigns/{id}/	Admin	Partial update
PUT	/api/campaigns/{id}/	Admin	Full update
DELETE	/api/campaigns/{id}/	Admin	Delete

Fields:

Field	Type	Required	Notes
name	string	Yes
description	string	Yes
start_time	datetime	Yes	ISO 8601
end_time	datetime	Yes	Must be after start_time
image	file	No	Campaign image (multipart)

Read-only computed fields: is_active, is_upcoming, is_ended

---

Models

ContactUs

Field	Type
name	CharField
email_or_phone	CharField
description	TextField
category	CharField (choices)
created_at	DateTimeField (auto)
updated_at	DateTimeField (auto)

Composition

Field	Type
name	CharField
description	TextField
image	ImageField (legacy)
created_at	DateTimeField (auto)
updated_at	DateTimeField (auto)

CompositionImage

Field	Type
composition	ForeignKey → Composition
image	ImageField
is_main	BooleanField
created_at	DateTimeField (auto)

DB constraint: only one is_main=True per composition.

Campaign

Field	Type
name	CharField
description	TextField
start_time	DateTimeField
end_time	DateTimeField
image	ImageField
created_at	DateTimeField (auto)
updated_at	DateTimeField (auto)

---

Media Files

Content	Path
Composition images	media/compositions/
Campaign images	media/campaigns/

---

Postman Collection

Import backend/Zoneco_ORG_API.postman_collection.json into Postman.

Set the base_url collection variable to your server address.

---

Persian Documentation

Full Persian API documentation: backend/API_DOCS_FA.md

---

HTTP Status Codes

Code	Meaning
200	OK
201	Created
204	Deleted (no body)
400	Invalid data
403	Forbidden (login required)
404	Not found