# GET /b2c/v1/categories

## GET /b2c/v1/categories

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

<div class="api-docs" id="bkmrk-">---

</div>### Endpoint Information

<div class="api-docs" id="bkmrk-url%3A-%2Fb2c%2Fv1%2Fcategor"><div class="endpoint-info"><div>**URL:** `/b2c/v1/categories`</div><div>**Method:** <span class="method-get">GET</span></div><div>**Controller:** `V1CategoryController@index`</div><div>**Middleware:** `web` (بدون JWT)</div><div>**Model:** `Category`</div><div>**Resource:** `CategoryResource`</div></div>---

</div>### پارامترهای ورودی (Query Parameters)

<div class="api-docs" id="bkmrk-%D9%86%D8%A7%D9%85-%D9%86%D9%88%D8%B9-%D8%A7%D9%84%D8%B2%D8%A7%D9%85%DB%8C-%D8%AA%D9%88%D8%B6%DB%8C%D8%AD"><table class="schema-table" dir="rtl"><thead><tr><th>نام</th><th>نوع</th><th>الزامی</th><th>توضیح</th></tr></thead><tbody><tr><td>`branch`</td><td>integer</td><td>✅</td><td>شناسه دفتر یا شعبه‌ای که دسته‌بندی‌ها به آن تعلق دارند</td></tr><tr><td>`type`</td><td>string</td><td>❌</td><td>نوع دسته‌بندی (مثلاً `article`، `product`، `destination`) برای فیلتر اختیاری</td></tr><tr><td>`page`</td><td>integer</td><td>❌</td><td>شماره صفحه برای صفحه‌بندی (به‌صورت پیش‌فرض ۱)</td></tr></tbody></table>

---

</div>### منطق پردازشی (Process Flow)

<div class="api-docs" id="bkmrk-%F0%9F%93%A5-%DB%B1.-%D8%AF%D8%B1%DB%8C%D8%A7%D9%81%D8%AA-%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1%D9%87"><div class="flowchart" dir="rtl"><div class="flow-item">📥 ۱. دریافت پارامترهای `branch`، `type` و `page` از Query</div><div class="flow-arrow">↓</div><div class="flow-item-process">⚙️ ۲. اجرای کوئری روی مدل `Category`:</div>- اعمال شرط `where('branch', branch)`
- در صورت وجود `type` → `where('type', type)`
- نمایش فقط دسته‌های سطح اول (`whereNull('main')`)

<div class="flow-arrow">↓</div><div class="flow-item-process">📑 ۳. صفحه‌بندی خروجی با `paginate(15)`.</div><div class="flow-arrow">↓</div><div class="flow-item-success">✅ ۴. بازگرداندن JSON شامل وضعیت، زمان، داده‌ها و لینک‌های صفحه‌بندی.</div></div>---

</div>### 📦 ساختار پاسخ 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"
  }
}
```

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

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

<div class="api-docs" id="bkmrk--1">---

</div>### نکات فنی و اجرایی

<div class="api-docs" id="bkmrk-%D8%AA%D9%85%D8%A7%D9%85-%D8%AF%D8%B3%D8%AA%D9%87%E2%80%8C%D9%87%D8%A7-%D8%A7%D8%B2-%D8%AC%D8%AF%D9%88%D9%84">- تمام دسته‌ها از جدول `categories` فیلتر می‌شوند و تنها سطح ریشه (main = NULL) نمایش داده می‌شود.
- در خروجی داده‌های هر رکورد توسط `CategoryResource` قالب‌بندی شده‌اند.
- صفحه‌بندی بر اساس ۱۵ آیتم در هر صفحه انجام می‌شود و لینک‌ها توسط Laravel Paginator تولید می‌شوند.
- پارامتر `branch` اجباری است؛ در صورت نبود، خروجی خالی یا خطای منطقی بازگردانده می‌شود.
- پاسخ شامل فیلد کمکی `time` جهت هماهنگی با دیگر APIهای B2C است.

---

</div>### 🚀 پیشنهاد بهبود آینده

<div class="api-docs" id="bkmrk-%D8%A7%D9%81%D8%B2%D9%88%D8%AF%D9%86-%D9%82%D8%A7%D8%A8%D9%84%DB%8C%D8%AA-includ">- افزودن قابلیت `includeChildren=true` برای لود درختی زیردسته‌ها همراه سطح اول.
- امکان تعیین `limit` دلخواه در Query برای انعطاف بیشتری در بخش Front.
- افزودن پارامتر `sort=popular|alphabetical` جهت کنترل ترتیب خروجی.

</div>