# GET /b2c/v1/online/accommodation/list

<div class="api-docs" id="bkmrk-"><div class="endpoint-section">  
</div></div>## List Accommodation Items

این اندپوینت فهرستی از اقامتگاه‌ها (هتل‌ها) را بر اساس شهر، IATA، یا شناسه‌ی مستقیم هتل بازیابی می‌کند. امکان اعمال فیلترهای متنوع شامل ستاره، نوع، نام، سرویس‌دهنده‌ها و محدوده‌ی تاریخی رزرو وجود دارد. در صورت انتخاب **only\_charters=true**، نتایج محدود به هتل‌های دارای چارتر فعال در بازه‌ی داده‌شده خواهند بود.

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

</div>### Endpoint Info

<div class="api-docs" id="bkmrk-url%3A-%2Fb2c%2Fv1%2Fonline%2F"><div class="endpoint-info"><div>**URL:** `/b2c/v1/online/accommodation/list`</div><div>**Method:** <span class="method-get">GET</span></div><div>**Controller:** `V1OnlineController@listAccommodation`</div><div>**Service Layer:** `LibBaseService::listAccommodation()`</div><div>**Auth:** Public Access (No JWT Required)</div></div>---

</div>### Query Parameters

<div class="api-docs" id="bkmrk-parameter-type-requi"><table class="schema-table" dir="rtl"><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>type</td><td>string</td><td>✅</td><td>نوع جستجو: یکی از مقادیر `city`، `iata` یا `accommodation`.</td></tr><tr><td>value</td><td>string|integer</td><td>✅</td><td>مقدار مرتبط با نوع؛ مثلاً نام شهر، کد IATA، یا شناسه هتل.</td></tr><tr><td>checkin\_date</td><td>date</td><td>✅</td><td>تاریخ ورود.</td></tr><tr><td>checkout\_date</td><td>date</td><td>✅</td><td>تاریخ خروج.</td></tr><tr><td>branch</td><td>integer</td><td>✅</td><td>شناسه‌ی شعبه برای چک چارترهای فعال.</td></tr><tr><td>filters\[only\_charters\]</td><td>boolean</td><td>❌</td><td>اگر true باشد فقط هتل‌هایی که چارتر فعال دارند بازگردانده می‌شوند.</td></tr><tr><td>filters\[stars\]\[\]</td><td>array</td><td>❌</td><td>لیست تعداد ستاره‌های مد نظر (مثلاً \[3,4,5\]).</td></tr><tr><td>filters\[types\]\[\]</td><td>array</td><td>❌</td><td>انواع اقامتگاه شامل `hotel`، `apartment`، `guesthouse` و ...</td></tr><tr><td>filters\[name\]</td><td>string</td><td>❌</td><td>جستجو بر اساس بخشی از نام فارسی هتل.</td></tr><tr><td>filters\[services\]\[\]</td><td>array</td><td>❌</td><td>لیست سرویس‌دهنده‌ها (مثلاً `snapptrip`، `sepehr`، `tport`، `airplus`).</td></tr><tr><td>paginate\[length\]</td><td>integer</td><td>❌</td><td>تعداد رکورد در هر صفحه (پیش‌فرض 30).</td></tr><tr><td>paginate\[start\]</td><td>integer</td><td>❌</td><td>شماره شروع ایندکس صفحه (پیش‌فرض 0).</td></tr></tbody></table>

---

</div>### Response Structure

<div class="api-docs" id="bkmrk-key-description-stat"><table class="schema-table" dir="rtl"><thead><tr><th>Key</th><th>Description</th></tr></thead><tbody><tr><td>Status</td><td>وضعیت پاسخ (true در صورت موفقیت).</td></tr><tr><td>Time</td><td>Timestamp زمان پاسخ.</td></tr><tr><td>Search</td><td>اطلاعات شناسایی‌شده برای نوع جستجو (شهر، کشور، یا هتل).</td></tr><tr><td>Data</td><td>لیست اقامتگاه‌ها در قالب `AccommodationListResource`.</td></tr><tr><td>Table</td><td>اطلاعات مربوط به صفحه‌بندی (total, per\_page, current\_page, last\_page, از، تا، next\_page).</td></tr></tbody></table>

</div>### Example Response (Success)

```json
{
  "Status": true,
  "Time": 1733742000,
  "Search": {
    "city": {
      "id": 396,
      "title": {"fa": "مشهد", "en": "Mashhad"},
      "country": {"fa": "ایران", "en": "Iran"},
      "category": {"title": "شهر"}
    }
  },
  "Data": [
    {
      "id": 2652,
      "fa_title": "اکسلسیور کیش",
      "en_title": "Excelsior Kish Hotel",
      "rate": 5,
      "type": "hotel",
      "city": "مشهد",
      "priority": 0,
      "mapping": {"airplus": true, "snapptrip": true}
    }
  ],
  "Table": {
    "total": 250,
    "per_page": 30,
    "current_page": 1,
    "last_page": 9,
    "from": 1,
    "to": 30,
    "next_page": 2
  }
}
```

### Example Response (Error)

```json
{
  "status": false,
  "time": 1733742053,
  "error": {
    "code": 1002,
    "message": "Invalid city or date format.",
    "trace": [ ... ]
  },
  "support": {
    "phone": "021-91016838 in 121",
    "email": "ict@airplus.app",
    "panel": "helpdesk.airplus.app"
  }
}
```

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

</div>### Technical Flow (Logic Overview)

<div class="api-docs" id="bkmrk-%D9%88%D8%B1%D9%88%D8%AF%DB%8C-%D8%AF%D8%B1%D8%AE%D9%88%D8%A7%D8%B3%D8%AA-%D8%B4%D8%A7%D9%85%D9%84-t"><div class="flowchart" dir="rtl"><div class="flow-item">ورودی درخواست شامل type، value، filters و paginate</div><div class="flow-arrow">↓</div><div class="flow-item-process">**Validate Pagination**  
اگر پارامتر paginate وجود نداشته یا کامل نیست، مقدار پیش‌فرض (length=30, start=0) ست می‌شود.</div><div class="flow-arrow">↓</div><div class="flow-item-process">**Determine Search Mode**  
بسته به `type`، داده از جدول‌های cities، states، countries یا hotels واکشی می‌شود.</div><div class="flow-arrow">↓</div><div class="flow-item-process">**Build Filter Query**  
روی جدول `hotels` با join بر روی `mapping_accommodations` انجام می‌شود.</div><div class="flow-arrow">↓</div><div class="flow-item-process">**Filter Logic**  
- ستاره‌ها (rate)  
- نوع اقامتگاه (type)  
- نام جزئی (fa_title LIKE '%name%')  
- وجود چارتر فعال بین تاریخ‌های واردشده.</div><div class="flow-arrow">↓</div><div class="flow-item-success">**Paginate &amp; Return**  
پاسخ شامل Search (محل جغرافیایی) + Data (Resource List) + Table meta.</div></div></div>