Skip to main content
#P1813

GET /b2c/v1/categories

GET /b2c/v1/categories

این اندپوینت برای دریافت فهرست دسته‌بندی‌ها (Categories) طراحی شده است. داده‌ها از جدول categories گرفته می‌شوند و امکان فیلتر بر اساس نوع (type) و شعبه (branch) وجود دارد. فقط دسته‌بندی‌های سطح اول (یعنی مواردی که main آن‌ها NULL است) بازگردانده می‌شوند.

Endpoint Information

URL: /b2c/v1/categories
Method: GET
Controller: V1CategoryController@index
Middleware: web (بدون JWT)
Model: Category
Resource: CategoryResource

پارامترهای ورودی (Query Parameters)

نام نوع الزامی توضیح
branch integer ✅ شناسه دفتر یا شعبه‌ای که دسته‌بندی‌ها به آن تعلق دارند
type string ❌ نوع دسته‌بندی (مثلاً article، product، destination) برای فیلتر اختیاری
page integer ❌ شماره صفحه برای صفحه‌بندی (به‌صورت پیش‌فرض ۱)

منطق پردازشی (Process Flow)

📥 ۱. دریافت پارامترهای branch، type و page از Query
↓
⚙️ ۲. اجرای کوئری روی مدل Category:
  • اعمال شرط where('branch', branch)
  • در صورت وجود type → where('type', type)
  • نمایش فقط دسته‌های سطح اول (whereNull('main'))
↓
📑 ۳. صفحه‌بندی خروجی با paginate(15).
↓
✅ ۴. بازگرداندن JSON شامل وضعیت، زمان، داده‌ها و لینک‌های صفحه‌بندی.

📦 ساختار پاسخ JSON

پاسخ موفق

{
  "status": true,
  "time": 1733806124,
  "data": [
    {
      "id": 12,
      "title": {
        "fa": "مقاصد محبوب",
        "en": "Popular Destinations"
      },
      "slug": "popular-destinations",
      "type": "article",
      "main": null,
      "cover": "https://cdn.site.com/uploads/categories/12.jpg",
      "created_at": "2025-11-25T07:10:00Z"
    },
    {
      "id": 13,
      "title": {
        "fa": "تورهای داخلی",
        "en": "Domestic Tours"
      },
      "slug": "domestic-tours",
      "type": "tour",
      "main": null,
      "cover": "https://cdn.site.com/uploads/categories/13.jpg"
    }
  ],
  "links": {
    "first": "https://api.domain.com/b2c/v1/categories?page=1",
    "last": "https://api.domain.com/b2c/v1/categories?page=10",
    "prev": null,
    "next": "https://api.domain.com/b2c/v1/categories?page=2"
  }
}

پاسخ خطا (نمونه)

{
  "status": false,
  "time": 1733806125,
  "message": "پارامتر branch ارسال نشده است."
}

نکات فنی و اجرایی

  • تمام دسته‌ها از جدول categories فیلتر می‌شوند و تنها سطح ریشه (main = NULL) نمایش داده می‌شود.
  • در خروجی داده‌های هر رکورد توسط CategoryResource قالب‌بندی شده‌اند.
  • صفحه‌بندی بر اساس ۱۵ آیتم در هر صفحه انجام می‌شود و لینک‌ها توسط Laravel Paginator تولید می‌شوند.
  • پارامتر branch اجباری است؛ در صورت نبود، خروجی خالی یا خطای منطقی بازگردانده می‌شود.
  • پاسخ شامل فیلد کمکی time جهت هماهنگی با دیگر APIهای B2C است.

🚀 پیشنهاد بهبود آینده

  • افزودن قابلیت includeChildren=true برای لود درختی زیردسته‌ها همراه سطح اول.
  • امکان تعیین limit دلخواه در Query برای انعطاف بیشتری در بخش Front.
  • افزودن پارامتر sort=popular|alphabetical جهت کنترل ترتیب خروجی.
Back to top