# POST /b2c/v1/online/search/{type}

<div class="api-docs" id="bkmrk-">  <div class="endpoint-section">  
</div></div>## Search Flights &amp; Trains

این اندپوینت برای جستجوی بلیط‌های سفر استفاده می‌شود.   
سیستم به صورت هوشمند بر اساس نوع درخواست (قطار یا پرواز)، ورودی‌ها را اعتبارسنجی کرده، اطلاعات تکمیلی مبدا/مقصد را از دیتابیس یا کش Redis استخراج می‌کند و نتایج جستجو را از سرویس‌های تجمیع‌کننده (Aggregators) بازمی‌گرداند.

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

  </div># Route Search

<div class="api-docs" id="bkmrk-url%3A-%2Fb2c%2Fv1%2Fonline%2F"><div class="endpoint-info"><div>**URL:** `/b2c/v1/online/search/{type}`</div><div>**Method:** <span class="method-post">POST</span></div><div>**Controller:** V1OnlineController@routeSearch</div><div>**Auth:** Optional (Handled manually via Pipeline)</div></div></div>### Path Parameters

<div class="api-docs" id="bkmrk-parameter-type-descr"><table class="schema-table" dir="rtl"><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td dir="ltr">{type}</td><td>String</td><td>نوع وسیله نقلیه. مقادیر مجاز: `train` یا `aircraft` (یا هر مقدار غیر train برای پرواز).</td></tr></tbody></table>

  </div>### Request Body Parameters

#### پارامترهای مشترک (Common)

<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 dir="ltr">branch</td><td>Integer</td><td>Yes</td><td>شناسه شعبه.</td></tr><tr><td dir="ltr">group</td><td>String</td><td>No</td><td>گروه کاربری (`b2c`, `b2b`, `b2e`, `colleague`). پیش‌فرض: `b2c`.</td></tr><tr><td dir="ltr">level</td><td>Integer</td><td>No</td><td>سطح دسترسی کاربر (پیش‌فرض: 1).</td></tr></tbody></table>

</div>#### اگر `type = 'train'` باشد:

<div class="api-docs" id="bkmrk-parameter-type-requi-1"><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 dir="ltr">origin</td><td>Integer</td><td>Yes</td><td>**شناسه شهر** مبدا (City ID) از جدول `cities`.</td></tr><tr><td dir="ltr">destination</td><td>Integer</td><td>Yes</td><td>**شناسه شهر** مقصد (City ID) از جدول `cities`.</td></tr><tr><td dir="ltr">departure</td><td>Datetime</td><td>Yes</td><td>تاریخ رفت (فرمت استاندارد).</td></tr><tr><td dir="ltr">returning</td><td>Datetime</td><td>No</td><td>تاریخ برگشت. باید بعد از تاریخ رفت باشد.</td></tr></tbody></table>

</div>#### اگر `type != 'train'` (پرواز) باشد:

<div class="api-docs" id="bkmrk-parameter-type-requi-2"><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 dir="ltr">origin</td><td>String</td><td>Yes</td><td>**کد IATA** فرودگاه مبدا (مانند `MHD`, `THR`).</td></tr><tr><td dir="ltr">destination</td><td>String</td><td>Yes</td><td>**کد IATA** فرودگاه مقصد.</td></tr><tr><td dir="ltr">departure\_date</td><td>Date</td><td>Yes</td><td>تاریخ رفت. <span style="color: red; font-size: 0.8em;">(توجه: نام پارامتر با قطار متفاوت است)</span>.</td></tr><tr><td dir="ltr">returning\_date</td><td>Date</td><td>No</td><td>تاریخ برگشت.</td></tr><tr><td dir="ltr">only\_charters</td><td>Boolean</td><td>No</td><td>فیلتر فقط پروازهای چارتر.</td></tr></tbody></table>

---

  </div>### Business Logic Details

#### ۱. احراز هویت اختیاری (Optional Pipeline Auth)

حتی اگر روت عمومی باشد، کد چک می‌کند اگر هدر `Authorization` وجود داشته باشد، درخواست را از پایپ‌لاین `AuthWithJWT` عبور می‌دهد. این کار برای اعمال تخفیف‌های خاص یا دسترسی‌های سطح کاربر (Level) انجام می‌شود.

#### ۲. اعتبارسنجی قطار (Train Validation)

برای جستجوی قطار اعتبارسنجی سخت‌گیرانه‌تری روی تاریخ‌ها انجام می‌شود:

<div class="api-docs" id="bkmrk-%D8%A7%DA%AF%D8%B1-%D9%81%D8%B1%D9%85%D8%AA-departure-%D8%A7"><div class="logic-box" dir="rtl">- اگر فرمت `departure` اشتباه باشد -&gt; **خطای 409** (کد 1000).
- اگر تاریخ برگشت قبل از رفت باشد -&gt; **خطای 409**.

</div></div>#### ۳. غنی‌سازی اطلاعات مبدا/مقصد (Metadata Enrichment)

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

<div class="api-docs" id="bkmrk-%D8%A8%D8%B1%D8%A7%DB%8C-%D9%BE%D8%B1%D9%88%D8%A7%D8%B2-%28string-i"><div class="logic-box" dir="rtl">- **برای پرواز (String input):** اطلاعات فرودگاه (IATA, Title, Country, State, City) را از جدول `airports` می‌گیرد. برای سرعت بیشتر، این اطلاعات در **Redis** با کلید `airports:{IATA}` کش می‌شوند.
- **برای قطار (Numeric input):** اطلاعات شهر (نام فارسی/انگلیسی، استان) را از جدول `cities` جوین شده با `states` دریافت می‌کند.

</div></div>#### ۴. فراخوانی سرویس پایه (Base Service)

<div class="api-docs" id="bkmrk-%D8%A8%D8%B1%D8%A7%DB%8C-%D9%82%D8%B7%D8%A7%D8%B1-%D9%85%D8%AA%D8%AF-basese"><div class="logic-box" dir="rtl">- برای قطار متد `BaseService::combineRoute` فراخوانی می‌شود.
- برای پرواز متد `LibBaseService::combineFlight` فراخوانی می‌شود.

</div>---

  </div>### Response Examples

#### پاسخ جستجوی قطار (Train Response)

ساختار پاسخ قطار شامل `payload` و `meta` است.

```json
{
    "payload": [
        // لیست قطارهای یافت شده از سرویس
        {
            "id": 105,
            "price": 2500000,
            "provider": "raja",
            "capacity": 4
        }
    ],
    "meta": {
        "search": {
            "origin": {
                "id": 37,
                "title": {"fa": "اصفهان", "en": "Isfahan"},
                "category": {"id": 5, "title": {"fa": "اصفهان", "en": "Isfahan"}}
            },
            "destination": {
                "id": 396,
                "title": {"fa": "مشهد", "en": "Mashhad"},
                "category": {"id": 10, "title": {"fa": "خراسان رضوی", "en": "Razavi Khorasan"}}
            },
            "departure": "2025-12-10",
            "returning": false
        },
        "timestamp": 1702123456
    }
}
```

#### پاسخ جستجوی پرواز (Flight Response)

ساختار پاسخ پرواز کمی متفاوت است و مستقیماً آرایه برمی‌گرداند.

```json
{
    "search": {
        "origin": {
            "id": 1,
            "iata": "MHD",
            "title": "فرودگاه هاشمی نژاد",
            "country": { "id": 100, "title_fa": "ایران" },
            "city": { "id": 396, "title_fa": "مشهد" }
        },
        "destination": {
            "id": 2,
            "iata": "THR",
            "title": "فرودگاه مهرآباد",
            "city": { "id": 1, "title_fa": "تهران" }
        },
        "departure_date": "2025-12-10",
        "returning_date": null
    },
    "data": [
        // لیست پروازهای یافت شده
        {
            "flight_id": "WS-123",
            "airline": "Mahan",
            "price": 15000000
        }
    ]
}
```

#### خطای اعتبارسنجی تاریخ (Train Error)

<div class="api-docs" id="bkmrk-status%3A-409-conflict"><div class="endpoint-info" style="background-color: #f2dede; border-color: #ebccd1; color: #a94442;">Status: 409 Conflict</div></div>```json
{
    "error": {
        "code": 1000,
        "message": "تاریخ شروع و پایان جستجو معتبر نمی باشد"
    }
}
```