#P1793
POST /b2c/v1/online/search/{type}
Search Flights & Trains
این اندپوینت برای جستجوی بلیطهای سفر استفاده میشود.
سیستم به صورت هوشمند بر اساس نوع درخواست (قطار یا پرواز)، ورودیها را اعتبارسنجی کرده، اطلاعات تکمیلی مبدا/مقصد را از دیتابیس یا کش Redis استخراج میکند و نتایج جستجو را از سرویسهای تجمیعکننده (Aggregators) بازمیگرداند.
Route Search
URL:
/b2c/v1/online/search/{type}Method: POST
Controller: V1OnlineController@routeSearch
Auth: Optional (Handled manually via Pipeline)
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| {type} | String | نوع وسیله نقلیه. مقادیر مجاز: train یا aircraft (یا هر مقدار غیر train برای پرواز). |
Request Body Parameters
پارامترهای مشترک (Common)
| Parameter | Type | Required | Description |
|---|---|---|---|
| branch | Integer | Yes | شناسه شعبه. |
| group | String | No | گروه کاربری (b2c, b2b, b2e, colleague). پیشفرض: b2c. |
| level | Integer | No | سطح دسترسی کاربر (پیشفرض: 1). |
اگر type = 'train' باشد:
| Parameter | Type | Required | Description |
|---|---|---|---|
| origin | Integer | Yes | شناسه شهر مبدا (City ID) از جدول cities. |
| destination | Integer | Yes | شناسه شهر مقصد (City ID) از جدول cities. |
| departure | Datetime | Yes | تاریخ رفت (فرمت استاندارد). |
| returning | Datetime | No | تاریخ برگشت. باید بعد از تاریخ رفت باشد. |
اگر type != 'train' (پرواز) باشد:
| Parameter | Type | Required | Description |
|---|---|---|---|
| origin | String | Yes | کد IATA فرودگاه مبدا (مانند MHD, THR). |
| destination | String | Yes | کد IATA فرودگاه مقصد. |
| departure_date | Date | Yes | تاریخ رفت. (توجه: نام پارامتر با قطار متفاوت است). |
| returning_date | Date | No | تاریخ برگشت. |
| only_charters | Boolean | No | فیلتر فقط پروازهای چارتر. |
Business Logic Details
۱. احراز هویت اختیاری (Optional Pipeline Auth)
حتی اگر روت عمومی باشد، کد چک میکند اگر هدر Authorization وجود داشته باشد، درخواست را از پایپلاین AuthWithJWT عبور میدهد. این کار برای اعمال تخفیفهای خاص یا دسترسیهای سطح کاربر (Level) انجام میشود.
۲. اعتبارسنجی قطار (Train Validation)
برای جستجوی قطار اعتبارسنجی سختگیرانهتری روی تاریخها انجام میشود:
- اگر فرمت
departureاشتباه باشد -> خطای 409 (کد 1000). - اگر تاریخ برگشت قبل از رفت باشد -> خطای 409.
۳. غنیسازی اطلاعات مبدا/مقصد (Metadata Enrichment)
سیستم قبل از پاسخدهی، اطلاعات کامل شهر یا فرودگاه را به پاسخ اضافه میکند:
- برای پرواز (String input): اطلاعات فرودگاه (IATA, Title, Country, State, City) را از جدول
airportsمیگیرد. برای سرعت بیشتر، این اطلاعات در Redis با کلیدairports:{IATA}کش میشوند. - برای قطار (Numeric input): اطلاعات شهر (نام فارسی/انگلیسی، استان) را از جدول
citiesجوین شده باstatesدریافت میکند.
۴. فراخوانی سرویس پایه (Base Service)
- برای قطار متد
BaseService::combineRouteفراخوانی میشود. - برای پرواز متد
LibBaseService::combineFlightفراخوانی میشود.
Response Examples
پاسخ جستجوی قطار (Train Response)
ساختار پاسخ قطار شامل payload و meta است.
{
"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)
ساختار پاسخ پرواز کمی متفاوت است و مستقیماً آرایه برمیگرداند.
{
"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)
Status: 409 Conflict
{
"error": {
"code": 1000,
"message": "تاریخ شروع و پایان جستجو معتبر نمی باشد"
}
}