parsshop-back/docs/user-addresses-api.md

User Addresses API

Base URL: /api

تمام endpointهای این فایل نیاز به احراز هویت دارند:

• Header: Authorization: Bearer <access_token>
• Content-Type: application/json

همه پاسخ‌ها داخل wrapper استاندارد برمی‌گردند:

{
  "success": true,
  "statusCode": 200,
  "path": "/api/users/me/addresses",
  "timestamp": "2026-03-30T07:00:00.000Z",
  "data": {}
}

Address Object

{
  "id": "7f95d2c5-5ef4-4a7d-94f9-2c7a0dcb3e40",
  "title": "خانه",
  "recipientName": "علی رضایی",
  "phone": "+989121234567",
  "province": "فارس",
  "city": "شیراز",
  "postalCode": "7183914511",
  "addressLine": "بلوار معالی آباد، کوچه 12، ساختمان پارس",
  "plaque": "24",
  "unit": "3",
  "isDefault": true,
  "createdAt": "2026-03-30T06:50:00.000Z",
  "updatedAt": "2026-03-30T06:50:00.000Z"
}

Validation Rules

فیلدهای بدنه برای ساخت آدرس:

• title: رشته، اجباری، طول 2..100
• recipientName: رشته، اجباری، طول 2..150
• phone: رشته، اجباری، طول 8..20
• province: رشته، اجباری، طول 2..100
• city: رشته، اجباری، طول 2..100
• postalCode: رشته، اختیاری، فقط رقم، الگوی ^[0-9]{5,20}$
• addressLine: رشته، اجباری، طول 5..500
• plaque: رشته، اختیاری، طول 1..50
• unit: رشته، اختیاری، طول 1..50
• isDefault: بولین، اختیاری

نکات:

• در PATCH همه فیلدها اختیاری هستند.
• به خاطر whitelist + forbidNonWhitelisted هر فیلد اضافه و ناشناخته با خطای 400 رد می‌شود.

1. دریافت لیست آدرس‌ها

GET /api/users/me/addresses

Behavior:

• فقط آدرس‌های کاربر لاگین‌شده را برمی‌گرداند.
• ترتیب خروجی: اول آدرس پیش‌فرض، بعد بقیه بر اساس جدیدترین.

Sample response:

{
  "success": true,
  "statusCode": 200,
  "path": "/api/users/me/addresses",
  "timestamp": "2026-03-30T07:00:00.000Z",
  "data": {
    "items": [
      {
        "id": "7f95d2c5-5ef4-4a7d-94f9-2c7a0dcb3e40",
        "title": "خانه",
        "recipientName": "علی رضایی",
        "phone": "+989121234567",
        "province": "فارس",
        "city": "شیراز",
        "postalCode": "7183914511",
        "addressLine": "بلوار معالی آباد، کوچه 12، ساختمان پارس",
        "plaque": "24",
        "unit": "3",
        "isDefault": true,
        "createdAt": "2026-03-30T06:50:00.000Z",
        "updatedAt": "2026-03-30T06:50:00.000Z"
      }
    ]
  }
}

2. ساخت آدرس جدید

POST /api/users/me/addresses

Sample request:

{
  "title": "خانه",
  "recipientName": "علی رضایی",
  "phone": "+989121234567",
  "province": "فارس",
  "city": "شیراز",
  "postalCode": "7183914511",
  "addressLine": "بلوار معالی آباد، کوچه 12، ساختمان پارس",
  "plaque": "24",
  "unit": "3",
  "isDefault": true
}

Sample response:

{
  "success": true,
  "statusCode": 201,
  "path": "/api/users/me/addresses",
  "timestamp": "2026-03-30T07:00:00.000Z",
  "data": {
    "id": "7f95d2c5-5ef4-4a7d-94f9-2c7a0dcb3e40",
    "title": "خانه",
    "recipientName": "علی رضایی",
    "phone": "+989121234567",
    "province": "فارس",
    "city": "شیراز",
    "postalCode": "7183914511",
    "addressLine": "بلوار معالی آباد، کوچه 12، ساختمان پارس",
    "plaque": "24",
    "unit": "3",
    "isDefault": true,
    "createdAt": "2026-03-30T06:50:00.000Z",
    "updatedAt": "2026-03-30T06:50:00.000Z"
  }
}

Business rules:

• اگر اولین آدرس کاربر باشد، خودکار isDefault = true می‌شود؛ حتی اگر در درخواست نفرستاده شود.
• اگر isDefault = true ارسال شود، هر آدرس پیش‌فرض قبلی از حالت پیش‌فرض خارج می‌شود.

3. ویرایش آدرس

PATCH /api/users/me/addresses/:addressId

Path params:

• addressId: شناسه آدرس

Sample request:

{
  "title": "محل کار",
  "city": "صدرا",
  "addressLine": "بلوار دانش، ساختمان فناوری",
  "isDefault": true
}

Sample response:

{
  "success": true,
  "statusCode": 200,
  "path": "/api/users/me/addresses/7f95d2c5-5ef4-4a7d-94f9-2c7a0dcb3e40",
  "timestamp": "2026-03-30T07:00:00.000Z",
  "data": {
    "id": "7f95d2c5-5ef4-4a7d-94f9-2c7a0dcb3e40",
    "title": "محل کار",
    "recipientName": "علی رضایی",
    "phone": "+989121234567",
    "province": "فارس",
    "city": "صدرا",
    "postalCode": "7183914511",
    "addressLine": "بلوار دانش، ساختمان فناوری",
    "plaque": "24",
    "unit": "3",
    "isDefault": true,
    "createdAt": "2026-03-30T06:50:00.000Z",
    "updatedAt": "2026-03-30T07:00:00.000Z"
  }
}

Business rules:

• همه فیلدها اختیاری هستند.
• اگر isDefault = true باشد، این آدرس پیش‌فرض می‌شود و بقیه از حالت پیش‌فرض خارج می‌شوند.
• اگر isDefault = false برای تنها آدرس پیش‌فرض کاربر ارسال شود، درخواست با 400 رد می‌شود.

4. تعیین آدرس پیش‌فرض

PATCH /api/users/me/addresses/:addressId/default

Path params:

• addressId: شناسه آدرس

Request body:

• ندارد

Sample response:

{
  "success": true,
  "statusCode": 200,
  "path": "/api/users/me/addresses/7f95d2c5-5ef4-4a7d-94f9-2c7a0dcb3e40/default",
  "timestamp": "2026-03-30T07:00:00.000Z",
  "data": {
    "id": "7f95d2c5-5ef4-4a7d-94f9-2c7a0dcb3e40",
    "title": "خانه",
    "recipientName": "علی رضایی",
    "phone": "+989121234567",
    "province": "فارس",
    "city": "شیراز",
    "postalCode": "7183914511",
    "addressLine": "بلوار معالی آباد، کوچه 12، ساختمان پارس",
    "plaque": "24",
    "unit": "3",
    "isDefault": true,
    "createdAt": "2026-03-30T06:50:00.000Z",
    "updatedAt": "2026-03-30T07:00:00.000Z"
  }
}

Business rules:

• همیشه فقط یک آدرس پیش‌فرض برای هر کاربر وجود دارد.

5. حذف آدرس

DELETE /api/users/me/addresses/:addressId

Path params:

• addressId: شناسه آدرس

Sample response:

{
  "success": true,
  "statusCode": 200,
  "path": "/api/users/me/addresses/7f95d2c5-5ef4-4a7d-94f9-2c7a0dcb3e40",
  "timestamp": "2026-03-30T07:00:00.000Z",
  "data": {
    "message": "Address deleted successfully",
    "addressId": "7f95d2c5-5ef4-4a7d-94f9-2c7a0dcb3e40"
  }
}

Business rules:

• اگر آدرس حذف‌شده پیش‌فرض باشد، جدیدترین آدرس باقی‌مانده خودکار پیش‌فرض می‌شود.
• اگر هیچ آدرسی باقی نماند، طبیعتا آدرس پیش‌فرضی هم وجود نخواهد داشت.

Error Cases

401 Unauthorized

وقتی توکن ارسال نشده باشد یا نامعتبر باشد.

404 Not Found

برای addressId نامعتبر یا آدرسی که متعلق به کاربر فعلی نیست.

نمونه پیام:

{
  "message": "Address not found",
  "error": "Not Found",
  "statusCode": 404
}

400 Bad Request

برای خطاهای validation یا ruleهای business.

نمونه‌ها:

• User must have at least one default address
• خطای فرمت postalCode
• ارسال فیلد ناشناخته در body