Frontend/AUTH_API.md

Authentication & Account API Documentation

فهرست مطالب

• مکانیزم احراز هویت
• فرمت کلی پاسخ‌ها
• مدل کاربر
• Auth Endpoints
  • ثبت‌نام
  • ورود با رمز عبور
  • درخواست OTP
  • تأیید OTP
  • رفرش توکن
• Account Endpoints
  • آپدیت پروفایل
• احراز هویت در درخواست‌ها
• کدهای خطا

---

مکانیزم احراز هویت

پروژه از JWT (JSON Web Token) با کتابخانه djangorestframework-simplejwt استفاده می‌کند.

• هر بار که کاربر ثبت‌نام یا لاگین موفق انجام می‌دهد، دو توکن دریافت می‌کند:
  • access — توکن کوتاه‌مدت برای احراز هویت درخواست‌ها
  • refresh — توکن بلندمدت برای گرفتن access جدید
• برای اندپوینت‌هایی که نیاز به احراز هویت دارند، باید توکن access را در هدر Authorization ارسال کنید:

Authorization: Bearer <access_token>

• Backend احراز هویت: MultiFieldBackend — کاربر می‌تواند با username، email یا phone_number لاگین کند.

---

فرمت کلی پاسخ‌ها

همه پاسخ‌ها از یک ساختار یکسان پیروی می‌کنند:

{
  "code": 200,
  "msg": "success",
  "data": { ... }
}

فیلد	نوع	توضیح
code	integer	کد وضعیت (مشابه HTTP status)
msg	string	پیام وضعیت ("success" یا متن خطا)
data	object	داده‌های برگشتی (در صورت وجود)
token	object	توکن‌های JWT (فقط در پاسخ‌های auth)

---

مدل کاربر

شیء AuthUser که در پاسخ‌های احراز هویت و پروفایل برگردانده می‌شود:

{
  "id": 1,
  "username": "john_doe",
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone_number": "09121234567"
}

---

Auth Endpoints

Base URL: /api/auth/

---

1. ثبت‌نام

POST /api/auth/register/

ساخت حساب کاربری جدید با نام کاربری، ایمیل، شماره موبایل و رمز عبور.

Request Body

{
  "username": "john_doe",
  "email": "john@example.com",
  "phone_number": "09121234567",
  "password": "securepass123",
  "first_name": "John",
  "last_name": "Doe"
}

فیلد	نوع	الزامی	توضیح
username	string	✅	حداکثر ۱۵۰ کاراکتر، یکتا
email	string	✅	فرمت ایمیل، یکتا
phone_number	string	✅	حداکثر ۳۲ کاراکتر، یکتا
password	string	✅	حداقل ۸ کاراکتر
first_name	string	❌	حداکثر ۱۵۰ کاراکتر
last_name	string	❌	حداکثر ۱۵۰ کاراکتر

Response موفق — 201 Created

{
  "code": 201,
  "msg": "success",
  "data": {
    "id": 1,
    "username": "john_doe",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "09121234567"
  },
  "token": {
    "access": "<access_token>",
    "refresh": "<refresh_token>"
  }
}

Response خطا — 400 Bad Request

{
  "code": 400,
  "msg": "A user with this username already exists."
}

پیام‌های خطای احتمالی:

• "A user with this username already exists."
• "A user with this email already exists."
• "A user with this phone number already exists."
• "A user with these credentials already exists."

---

2. ورود با رمز عبور

POST /api/auth/login/

ورود با استفاده از username، email یا phone_number به همراه رمز عبور.

Request Body

{
  "identifier": "john_doe",
  "password": "securepass123"
}

فیلد	نوع	الزامی	توضیح
identifier	string	✅	می‌تواند username، email یا phone_number باشد
password	string	✅	رمز عبور کاربر

Response موفق — 200 OK

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 1,
    "username": "john_doe",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "09121234567"
  },
  "token": {
    "access": "<access_token>",
    "refresh": "<refresh_token>"
  }
}

Response خطا — 401 Unauthorized

{
  "code": 401,
  "msg": "Invalid credentials."
}

---

3. درخواست OTP

POST /api/auth/request-otp/

⚠️ این endpoint در حال حاضر در urls.py کامنت شده است (غیرفعال).

ارسال کد یکبار مصرف (OTP) به شماره موبایل از طریق SMS.ir.

Request Body

{
  "phone_number": "09121234567"
}

فیلد	نوع	الزامی	توضیح
phone_number	string	✅	حداکثر ۳۲ کاراکتر

Response موفق — 200 OK

{
  "code": 200,
  "msg": "success",
  "token": "<otp_token>"
}

فیلد	توضیح
token	توکن امضاشده که باید در مرحله verify-otp ارسال شود
sms_warning	(اختیاری) در صورت شکست ارسال پیامک ظاهر می‌شود
debug_otp	(اختیاری) فقط در حالت DEBUG=True — کد OTP در پاسخ می‌آید

کد OTP مدت اعتبار ۳۰۰ ثانیه (۵ دقیقه) دارد.

---

4. تأیید OTP

POST /api/auth/verify-otp/

⚠️ این endpoint در حال حاضر در urls.py کامنت شده است (غیرفعال).

تأیید کد OTP دریافت‌شده و ورود/ثبت‌نام خودکار کاربر.

Request Body

{
  "token": "<otp_token>",
  "otp_code": "123456"
}

فیلد	نوع	الزامی	توضیح
token	string	✅	توکن دریافت‌شده از مرحله request-otp
otp_code	string	✅	کد ۶ رقمی ارسال‌شده به موبایل

Response موفق — 200 OK

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 1,
    "username": "09121234567",
    "email": "09121234567@otp.local",
    "first_name": "",
    "last_name": "",
    "phone_number": "09121234567"
  },
  "token": {
    "access": "<access_token>",
    "refresh": "<refresh_token>"
  }
}

اگر کاربر با این شماره موبایل قبلاً ثبت‌نام نکرده باشد، حساب جدید به‌صورت خودکار ساخته می‌شود.

Response خطا — 400 Bad Request

{
  "code": 400,
  "msg": "Token is invalid or expired."
}

یا:

{
  "code": 400,
  "msg": "OTP code is invalid or expired."
}

---

5. رفرش توکن

POST /api/auth/token/refresh/

دریافت access token جدید با استفاده از refresh token.

این endpoint توسط djangorestframework-simplejwt به‌صورت پیش‌فرض فراهم می‌شود.

Request Body

{
  "refresh": "<refresh_token>"
}

Response موفق — 200 OK

{
  "access": "<new_access_token>"
}

---

Account Endpoints

Base URL: /api/account/

---

1. آپدیت پروفایل

PATCH /api/account/profile/

🔒 نیاز به احراز هویت دارد — هدر Authorization: Bearer <access_token> الزامی است.

ویرایش اطلاعات پروفایل کاربر لاگین‌شده.

Request Body

همه فیلدها اختیاری هستند (partial update):

{
  "first_name": "علی",
  "last_name": "احمدی",
  "email": "new_email@example.com"
}

فیلد	نوع	الزامی	توضیح
first_name	string	❌	حداکثر ۱۵۰ کاراکتر
last_name	string	❌	حداکثر ۱۵۰ کاراکتر
email	string	❌	فرمت ایمیل معتبر

Response موفق — 200 OK

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 1,
    "username": "john_doe",
    "email": "new_email@example.com",
    "first_name": "علی",
    "last_name": "احمدی",
    "phone_number": "09121234567"
  }
}

Response خطا — 401 Unauthorized

در صورت نبود یا منقضی بودن توکن:

{
  "detail": "Authentication credentials were not provided."
}

---

احراز هویت در درخواست‌ها

برای اندپوینت‌هایی که نیاز به احراز هویت دارند (مانند PATCH /api/account/profile/)، توکن access را در هدر HTTP ارسال کنید:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

چرخه عمر توکن

[ثبت‌نام / لاگین]
       ↓
دریافت access + refresh
       ↓
ارسال درخواست‌ها با access
       ↓
منقضی شدن access (401)
       ↓
ارسال refresh به POST /api/auth/token/refresh/
       ↓
دریافت access جدید

---

کدهای خطا

HTTP Status	code	معنا
201	201	ثبت‌نام موفق
200	200	عملیات موفق
400	400	داده‌های نامعتبر یا OTP/توکن اشتباه
401	401	احراز هویت ناموفق (رمز اشتباه یا بدون توکن)

پاسخ‌های خطای اعتبارسنجی serializer (مانند فیلد اجباری) با فرمت استاندارد DRF برگردانده می‌شوند:

{
  "field_name": ["This field is required."]
}