GetAvailableOneWayFlights | BulkAvailability | پرواز | مستندات وب سرویس سپهر

متد GetAvailableOneWayFlights

این متد برای دریافت اطلاعات ظرفیت و نرخ پروازها براساس یک بازه تاریخی استفاده می شود.

کاربرد این متدها برای زمانی است که شما می خواهید پروازها را در سیستم خود Cache کنید و سپس درخواست های availability را از Cache خود پاسخ دهید.

با توجه به اینکه تجربه نشان داده است تغییرات ظرفیت و نرخ روی پروازهای تاریخ نزدیک (مثلا سه روز آینده) خیلی بیشتر از تغییرات پروازهای دورتر می باشد، بهینه ترین حالت این است که شما پروازهای تاریخ نزدیک را زود به زودتر از پروازهای تاریخ دورتر دریافت و به روزرسانی نمایید.

این متد فقط پروازهای OnTime را خروجی می دهد و پروازهایی که Close شده باشند یا ظرفیت آنها به پایان رسیده باشند در خروجی نمایش داده نمی شوند.

پروازهای دریافت شده را به دو روش می توانید در Cache خود ذخیره نمایید:

جایگزین کردن کل پروازها

در این روش شما آن پروازهایی که در بازه تاریخی درخواستی که ارسال کردید را از Cache خود پاک کرده و پروازهای جدید را ثبت می کنید. این روش پیاده سازی بسیار ساده ای داشته ولی فشار زیادی را روی IO دیتابیس Cache شما قرار می دهد. بنابراین پیشنهاد ما این است که فقط زمانی از این روش استفاده کنید که از دیتابیس های In-Memory مانند Redis برای Cache خود استفاده می کنید.
مقایسه یک به یک

در این روش شما باید پروازهای دیتابیس خود را به صورت تک به تک با پروازهای دریافت شده از وب سرویس مقایسه کنید و اگر اطلاعات پرواز تغییر کرده بود آنگاه آن پرواز را در دیتابیس خود replace کنید. همچنین پروازهایی که در دیتابیس شما وجود دارند ولی در خروجی وب سرویس وجود ندارند را از دیتابیس خود پاک کنید. زیرا این پروازها Close شده اند و دیگر ظرفیت خالی ندارند و شما باید آنها را از دیتابیس خود حذف نمایید.

پیاده سازی این روش نسبت به روش اول پرهزینه تر است و زمان توسعه و منابع بیشتری از سرور شما را مصرف خواهد کرد، ولی مناسب حالتی است که شما از دیتابیس های غیر In-Memory برای Cache خود استفاده می کنید.

نکته: برای پیدا کردن و مقایسه کردن پروازهای دیتابیس خود با لیست پروازهایی که وب سرویس به شما خروجی داده است از کلید شماره پرواز + تاریخ + مسیر استفاده نمایید. دقت نمایید که ساعت پرواز جزو کلید پرواز نیست و فقط قسمت تاریخ جزو کلید پرواز می باشد. در صورتی که ساعت را هم جزو کلید در نظر بگیرید، زمانی که ساعت یک پرواز تغییر پیدا کند، در پیدا کردن و مقایسه کردن آن به مشکل برخورد خواهید کرد. همچین در صورتی که از چند تامین کننده مختلف پرواز دریافت کنید، بهتر است Id آن تامین کننده را نیز جزو کلید در نظر بگیرید. یا شاید بهتر است اینطور گفته شود که پروازهای هر تامین کننده را در فضای جداگانه نگهداری کنید.

API Endpoint

POST https://{SupplierWebsiteUrl}/api/Partners/Flight/BulkAvailability/V18/GetAvailableOneWayFlights

Request Parameters

Username

string

required

نام کاربری

در صورتی که شما یک موتور جستجو هستید و قصد فروش نداشته و فقط می خواهید اطلاعات پروازهای عمومی را بدست آورید، نام کاربری را public ارسال نمایید.
Password

string

required

رمز عبور به صورت MD5 شده
FromDate

string

required

تاریخ شروع برای فیلتر کردن پروازها با فرمت yyyy-MM-dd میلادی.
ToDate

string

required

تاریخ پایان برای فیلتر کردن پروازها با فرمت yyyy-MM-dd میلادی.
FlightSource

string enum

required

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

All

تمامی پروازهای موجود (چه متعلق به تأمین‌کننده مورد درخواست و چه دریافت‌شده از سایر تأمین‌کنندگان).

OwnedFlight

فقط پروازهایی که تأمین‌کننده‌ای که به آن درخواست ارسال کرده‌اید مالک نرخ و ظرفیت آن‌هاست.

ThirdPartyFlight

فقط پروازهایی که تأمین‌کننده مورد درخواست، مالک نرخ و ظرفیت آن‌ها نیست و آن‌ها را از طریق وب‌سرویس از تأمین‌کننده دیگری دریافت کرده است (پروازهای وب سرویسی یا واسطه‌ای).

در زمان استفاده از سپهرهاب، مقدار این فیلد باید All یا ThirdPartyFlight ارسال شود.
PageNumber

integer

required

این فیلد جهت مدیریت صفحه‌بندی (Pagination) برای دریافت لیست پروازها استفاده می‌شود. با توجه به اینکه در هر پاسخ حداکثر ۱۰۰۰ پرواز ارائه می‌شود، برای دریافت تمامی نتایج باید از مکانیسم زیر پیروی کنید:
1. شروع پیمایش: برای دریافت اولین صفحه، مقدار PageNumber را برابر با 1 قرار دهید.
2. ادامه پیمایش: پس از هر درخواست، وضعیت فیلد HasNextPage را در خروجی بررسی کنید:
  - در صورت true بودن: به معنای وجود صفحات بعدی است؛ مقدار PageNumber را یک واحد افزایش داده و درخواست بعدی را ارسال کنید.
  - در صورت false بودن: پیمایش به پایان رسیده و تمام نتایج دریافت شده‌اند.
⚠️ نکته بسیار مهم (مدیریت پروازهای تکراری)

ممکن است در طول فرآیند صفحه‌بندی، پروازهای تکراری در صفحات مختلف بازگردانده شوند. برای مثال، پروازی که در صفحه اول دریافت شده، ممکن است مجدداً در صفحه دوم نیز تکرار شود. مدیریت و حذف این موارد بر عهده کلاینت است.
- نحوه تشخیص تکراری: برای شناسایی پروازهای تکراری، ترکیبی از فیلدهای زیر را به عنوان «کلید یکتا» در نظر بگیرید:
- FlightNumber + DepartureDate + Origin + Destination
- توجه: در این ترکیب، از فیلد DepartureDate (فقط بخش تاریخ پرواز) استفاده شود و نیازی به استفاده از ساعت پرواز نیست.
- پیشنهاد فنی: برای بهینه‌سازی عملکرد و افزایش سرعت پردازش در سمت کلاینت، پیشنهاد می‌شود از ساختار داده‌ای HashSet (در دات‌نت یا معادل آن در سایر زبان‌ها) برای ذخیره کلیدهای پردازش‌شده و فیلتر کردن موارد تکراری استفاده کنید.
جهت مشاهده پیاده سازی این فرایند به بخش نمونه کد (pseudo code) که در ادامه آمده است مراجعه نمایید.
Culture

string enum

required

مشخص‌کننده زبان متن‌های بازگشتی در پاسخ سرویس. مقادیر پذیرفته شده عبارتند از: fa-IR ، en-US و ar-IQ

Sample Request

curl -X POST https://SepehrApiTest.ir/api/Partners/Flight/BulkAvailability/V18/GetAvailableOneWayFlights \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip, deflate" \
  -d '{
    "UserName": "testdev1",
    "Password": "25f9e794323b453885f5181f1b624d0b",
    "FromDate": "2026-05-27",
    "ToDate": "2026-05-30",
    "FlightSource": "All",
    "PageNumber": 1,
    "Culture": "fa-IR"
}'

نمونه کد (pseudo code) دریافت پروازها و مدیریت Paging و حذف آیتم های تکراری

در ادامه، الگوریتم پیشنهادی جهت مدیریت صفحه‌بندی (Pagination) و فیلتر کردن پروازهای تکراری به صورت شبه‌کد ارائه شده است:

// 1. ساختار داده برای ذخیره دیتا نهایی
var allUniqueFlights = new List<Flight>();
var allUniqueRoundTripSearchRequireds = new List<RoundTripSearchRequired>();

// 2. استفاده از HashSet برای شناسایی آیتم های تکراری با سرعت O(1)
var processedFlightKeys = new HashSet<string>();
var processedRoundTripSearchRequiredKeys = new HashSet<string>();

int currentPage = 1;
bool hasNextPage = true;

while (hasNextPage)
{
    // ارسال درخواست به وب‌سرویس
    var response = GetAvailableOneWayFlights(pageNumber: currentPage);

    foreach (var flight in response.FlightList)
    {
        // ایجاد کلید یکتا: ترکیب فیلدهای مشخص شده
        string uniqueKey = $"{flight.FlightNumber}_{flight.DepartureDateTime.ToString("yyyyMMdd")}_{flight.Origin}_{flight.Destination}";

        // بررسی وجود پرواز در لیست پردازش شده
        if (!processedFlightKeys.Contains(uniqueKey))
        {
            // اگر تکراری نبود، به لیست نهایی اضافه کن
            allUniqueFlights.Add(flight);

            // کلید را به HashSet اضافه کن تا در تکرارهای بعدی شناسایی شود
            processedFlightKeys.Add(uniqueKey);
        }
    }

    foreach (var roundTripSearchRequired in response.RoundTripSearchRequiredList)
    {
        // ایجاد کلید یکتا: ترکیب فیلدهای مشخص شده
        string uniqueKey = $"{roundTripSearchRequired.Origin}_{roundTripSearchRequired.Destination}_{roundTripSearchRequired.Date}";

        // بررسی وجود آیتم در لیست پردازش شده
        if (!processedRoundTripSearchRequiredKeys.Contains(uniqueKey))
        {
            // اگر تکراری نبود، به لیست نهایی اضافه کن
            allUniqueRoundTripSearchRequireds.Add(roundTripSearchRequired);

            // کلید را به HashSet اضافه کن تا در تکرارهای بعدی شناسایی شود
            processedRoundTripSearchRequiredKeys.Add(uniqueKey);
        }
    }

    // به‌روزرسانی وضعیت صفحه‌بندی
    hasNextPage = response.HasNextPage;
    currentPage++;
}

Response Parameters

CurrencyCode

string

این فیلد مشخص می کند که نرخ های برگشتی بر اساس چه ارزی می باشد. مقدار آن بستگی به این دارد که ارز کاربر شما در سایت تامین کننده چه چیزی تعیین شده باشد. مثلا اگر کاربر شما به صورت ریالی باشد مقدار آن IRR و اگر دلاری باشد مقدار آن USD خواهد بود.
HasNextPage

boolean

وب‌سرویس به صورت پیش‌فرض در هر پاسخ، حداکثر ۱۰۰۰ نتیجه را بازمی‌گرداند. فیلد HasNextPage نشان‌دهنده وجود صفحات بعدی است:
- مقدار true: یعنی نتایج بیشتری در دسترس است. در این صورت، کلاینت باید مقدار PageNumber را در درخواست بعدی یک واحد افزایش داده و مجدداً فراخوانی را انجام دهد. این فرآیند باید تا زمانی که مقدار HasNextPage برابر با false شود، تکرار گردد.
- مقدار false: یعنی تمام نتایج با موفقیت دریافت شده‌اند.
جهت مشاهده پیاده‌سازی این فرآیند، به بخش «نمونه کد» مراجعه کنید.
FlightList

list of Flight

لیست پروازها

+ نمایش ویژگی‌های زیرمجموعه
- FlightList.FlightNumber
  
  string
  
  شماره پرواز
- FlightList.DepartureDateTime
  
  string
  
  تاریخ پرواز با فرمت yyyy-MM-dd HH:mm به زمان محلی مبدا
- FlightList.Origin
  
  string
  
  کد یاتای سه حرفی فرودگاه مبدا
- FlightList.Destination
  
  string
  
  کد یاتای سه حرفی فرودگاه مقصد
- FlightList.Aircraft
  
  string
  
  کد یاتای نوع هواپیما.
  
  جهت مشاهده کد یاتا انواع هواپیما اینجا کلیک نمایید
- FlightList.ArrivalDateTime
  
  string
  
  زمان رسیدن پرواز به مقصد با فرمت yyyy-MM-dd HH:mm به زمان محلی مقصد
- FlightList.Duration
  
  number
  
  طول مدت پرواز بر حسب دقیقه
  
  در صورتی که در سیستم خود طول مدت پرواز را نمایش می دهید، بهتر است به جای بدست آوردن تفاوت بین DepartureDateTime و ArrivalDateTime، از مقدار این فیلد استفاده نمایید. زیرا بدست آوردن تفاوت بر اساس DepartureDateTime و ArrivalDateTime نیازمند در نظر گرفتن ناحیه زمانی مبدا و مقصد بوده و یا حتی در مواردی که مبدا و مقصد یکسان بوده ولی ساعت ها تغییر کنند (مانند اول فروردین یا اول مهرماه) بدست آوردن این تفاوت، نیازمند عملیات پیچیده است. بنابراین بهتر است از مقدار این فیلد استفاده نمایید.
- FlightList.Airline
  
  string
  
  کد یاتا ایرلاین
- FlightList.Remarks
  
  string
  
  اگر تامین کننده توضیحاتی در خصوص این پرواز ثبت کرده باشد، این توضیحات به صورت متن در این فیلد خروجی داده می شود.
  
  عموما شما نیازی به استفاده از این فیلد نخواهید داشت و می توانید آن را نادیده بگیرید.
- FlightList.Source
  
  string enum
  
  این فیلد نشان می‌دهد پروازِ برگردانده‌شده از چه نوع منبعی تأمین شده است (از نظر مالکیت نرخ و ظرفیت). مقدار این فیلد یکی از گزینه‌های زیر است:
  
  Owned
  
  تأمین‌کننده‌ای که به آن درخواست داده‌اید، مالک مستقیمِ نرخ و ظرفیت این پرواز است؛ یعنی یا خودِ ایرلاین است که پرواز را در سیستم رزرواسیون سپهر ایجاد کرده، یا چارترکننده اصلی.
  
  ThirdParty
  
  تأمین‌کننده‌ای که به آن درخواست داده‌اید، مالک نرخ و ظرفیت این پرواز نیست و صرفاً نقش واسط دارد؛ یعنی پرواز را از طریق وب‌سرویس از تأمین‌کننده دیگری دریافت کرده و ارائه می‌کند.
- FlightList.Stop1
  
  Complex type
  
  در صورتی که پرواز دارای Stop باشد، اطلاعات اولین توقف در این فیلد خروجی داده خواهد شد.
  
  در پروزهای Stop دار، در زمان توقف، مسافر از هواپیما پیاده نشده و همچنین نیازی به جابجایی بار نیست. معمولا این گونه توقف ها بابت پیاده یا سوار کردن مسافران جدید یا سوخت گیری انجام می پذیرد. و در هر صورتی مسافران قبلی در زمان توقف در هواپیما باقی مانده و نیازی به ترک هواپیما نمی باشد.
  
  + نمایش ویژگی‌های زیرمجموعه
  - FlightList.Stop1.AirportIataCode
    
    string
    
    کد یاتا فرودگاه محل توقف
  - FlightList.Stop1.FlightDurationUntilThisStopInMinute
    
    number
    
    طول مدت پرواز تا رسیدن به فرودگاه محل توقف.
    
    مقدار این فیلد بر اساس دقیقه می باشد.
  - FlightList.Stop1.StopDurationInMinute
    
    number
    
    طول مدت توقف در فرودگاه
    
    مقدار این فیلد بر اساس دقیقه می باشد.
  - FlightList.Stop1.ArrivalDateTime
    
    string
    
    زمان ورود به فرودگاه محل توقف
    
    بر اساس زمان محلی و با فرمت yyyy-MM-dd HH:mm
  - FlightList.Stop1.DepartureDateTime
    
    string
    
    زمان خروج از فرودگاه محل توقف
    
    بر اساس زمان محلی و با فرمت yyyy-MM-dd HH:mm
    
    جهت بررسی این فیلد می توانید از تست سناریوهای زیر استفاده نمایید:
    
    تست سناریو شماره 10 پرواز چارتری
- FlightList.Stop2
  
  Complex type
  
  در صورتی که پرواز دارای بیش از یک Stop باشد، اطلاعات مربوط به توقف دوم توسط این فیلد خروجی داده می شود.
  
  ساختار فرمت آن مشابه فیلد Stop1 می باشد.
  
  جهت بررسی این فیلد می توانید از تست سناریوهای زیر استفاده نمایید:
  
  تست سناریو شماره 11 پرواز چارتری
- FlightList.FlightClassList
  
  Complex type
  
  اطلاعات مربوط به کلاس پروازی
  
  + نمایش ویژگی‌های زیرمجموعه
  - FlightList.FlightClassList.CabinType
    
    string
    
    نوع کابین کلاس پروازی که می تواند یکی از موارد زیر را داشته باشد:
    
    Economy
    
    EconomyPlus
    
    PremiumEconomy
    
    Business
    
    BusinessComfort
    
    BusinessPremium
    
    First
    
    جهت بررسی این فیلد می توانید از تست سناریوهای زیر استفاده نمایید:
    
    تست سناریو شماره 18 پرواز چارتری
    
    تست سناریو شماره 19 پرواز چارتری
    
    تست سناریو شماره 20 پرواز چارتری
    
    تست سناریو شماره 21 پرواز چارتری
  - FlightList.FlightClassList.BookingCode
    
    string
    
    معمولا ترکیب یک یا دو حرف بوده و مشخص کننده نوع BookingCode می باشد. مانند Y یا M.
    
    طول این فیلد حداکثر 3 کاراکتر می باشد.
  - FlightList.FlightClassList.FareName
    
    string
    
    نام Fare کلاس پروازی که می تواند ترکیب طولانی از حروف و اعداد باشد مانند THRMHD137. این نام در زمان رزرو گرفتن باید ارسال شود تا مشخص کند شما می خواهید روی چه کلاس پروازی رزرو خود را انجام دهید.
    
    طول این فیلد حداکثر 50 کاراکتر می باشد.
  - FlightList.FlightClassList.AvailableSeat
    
    number
    
    تعداد صندلی موجود برای رزرو روی کلاس پروازی.
  - FlightList.FlightClassList.AdultFare
    
    Complext type
    
    اطلاعات نرخی مربوط به یک نفر بزرگسال
    
    + نمایش ویژگی‌های زیرمجموعه
    
    FlightList.FlightClassList.AdultFare.BaseFare
    
    decimal
    
    نرخ پایه
    
    FlightList.FlightClassList.AdultFare.Tax
    
    decimal
    
    مجموع Tax. تعریف یا عدم تعریف Tax بستگی به تامین کننده دارد. ایرلاین‌هایی مانند هواپیمایی آوا حتماً Tax دارند، اما چارترکننده‌ها ممکن است به انتخاب خود روی پروازها Tax تعریف کرده باشند یا نکرده باشند.
    
    FlightList.FlightClassList.AdultFare.TotalFare
    
    decimal
    
    حاصل جمع BaseFare و Tax. در صورتی که Tax تعریف نشده باشد (مقدار صفر)، مقدار آن برابر BaseFare می باشد.
    
    FlightList.FlightClassList.AdultFare.Commission
    
    decimal
    
    مبلغ کمیسیون که به شما تعلق میگیرد.
    
    در صورتی که به میزان کمیسیون بر اساس درصد نیاز دارید، باید مقدار Commission را تقسیم بر TotalFare نموده و سپس در 100 ضرب نمایید.
    
    FlightList.FlightClassList.AdultFare.Markup
    
    decimal
    
    مبلغ روکشی.
    
    در صورتی که تامین کننده مبلغی را به عنوان حق سرویس به نرخ بلیط اضافه کرده باشد، مبلغ فوق در این فیلد خروجی داده می گردد.
    
    این فیلد فقط روی پروازهای وب سرویسی یک تامین کننده کاربرد دارد و روی پروازهای چارتری که سهمیه خود تامین کننده باشد این فیلد همواره صفر خواهد بود.
    
    FlightList.FlightClassList.AdultFare.Payable
    
    decimal
    
    مبلغ نهایی قابل پرداخت به تأمین‌کننده بابت بلیت بزرگسال.
    
    این مبلغ هنگام رزرو بلیت، به‌عنوان بدهکاری در حساب شما ثبت می‌شود و از فرمول زیر محاسبه می‌گردد:
    
    Payable = TotalFare - Commission + Markup
    
    موارد استفاده:
    
    ثبت سند حسابداری: برای ثبت صحیح بدهکاری ناشی از رزرو بلیت در سیستم مالی داخلی شما.
    
    بررسی تطابق قیمت (Price Cross-Check): هنگام فراخوانی متدهای Lock یا Book، مقدار این فیلد را ارسال کنید تا قیمت بلیت با نرخ ثبت‌شده در سیستم تأمین‌کننده مقایسه شود و از ادامه فرایند در صورت مغایرت قیمت جلوگیری شود.
    
    نکات مهم:
    
    نمایش قیمت به مسافر: معمولاً باید مبلغ TotalFare + Markup را به‌عنوان قیمت بلیت به مسافر خود نمایش دهید.
    
    عدم نمایش Payable به مسافر: این فیلد عمدتاً برای محاسبات مالی داخلی و بررسی تطابق قیمت هنگام رزرو کاربرد دارد و لزوماً معادل مبلغی نیست که مسافر بابت خرید بلیت پرداخت می‌کند.
  - FlightList.FlightClassList.ChildFare
    
    Complext type
    
    اطلاعات نرخی مربوط به یک نفر کودک
    
    ساختار آن شبیه به AdultFare می باشد
  - FlightList.FlightClassList.InfantFare
    
    Complext type
    
    اطلاعات نرخی مربوط به یک نفر نوزاد
    
    ساختار آن شبیه به AdultFare می باشد
  - FlightList.FlightClassList.AdultFreeBaggage
    
    Complex type
    
    اطلاعات مربوط به بار مجاز یک نفر بزرگسال
    
    + نمایش ویژگی‌های زیرمجموعه
    
    FlightList.FlightClassList.AdultFreeBaggage.CheckedBaggageQuantity
    
    number
    
    تعداد چمدان بار مجاز جهت قسمت بار هواپیما
    
    FlightList.FlightClassList.AdultFreeBaggage.CheckedBaggageTotalWeight
    
    number
    
    مجموع وزن بار مجاز جهت قسمت بار هواپیما
    
    FlightList.FlightClassList.AdultFreeBaggage.HandBaggageQuantity
    
    number
    
    تعداد کیف دستی قابل حمل به داخل هواپیما
    
    FlightList.FlightClassList.AdultFreeBaggage.HandBaggageTotalWeight
    
    number
    
    مجموع وزن کیف دستی قابل حمل به داخل هواپیما
  - FlightList.FlightClassList.ChildFreeBaggage
    
    Complex type
    
    اطلاعات مربوط به بار مجاز یک نفر کودک
    
    ساختار آن شبیه به AdultFreeBaggage می باشد.
  - FlightList.FlightClassList.InfantFreeBaggage
    
    Complex type
    
    اطلاعات مربوط به بار مجاز یک نفر نوزاد
    
    ساختار آن شبیه به AdultFreeBaggage می باشد.
  - FlightList.FlightClassList.CancelationPolicyList
    
    Complex type
    
    لیستی از اطلاعات و قوانین مربوط به استرداد بلیط به زبان های مختلف
    
    + نمایش ویژگی‌های زیرمجموعه
    
    FlightList.FlightClassList.CancelationPolicyList.Culture
    
    string
    
    این فیلد زبانی که متن جریمه بر اساس آن تولید شده است را مشخص می کند.
    
    در حال حاضر متن جریمه استرداد با دو زبان fa-IR و en-US خروجی داده می شود.
    
    FlightList.FlightClassList.CancelationPolicyList.Text
    
    string
    
    متن جریمه استرداد
    
    نکته: فرمت و جمله بندی اطلاعات داخل این فیلد ممکن است بدون اطلاع قبلی تغییر پیدا کند، بنابراین تا حد امکان از Parse کردن اطلاعات داخل این فیلد خودداری نمایید و عین جملاتی که این در این فیلد خروجی داده می شود را به کاربر خود نمایش دهید.
  - FlightList.FlightClassList.PermittedNationalityList
    
    List of string
    
    لیست ملیت های قابل رزرو
    
    کد 2 کاراکتری کشور ملیت هایی که مجاز به رزرو می باشند در این لیست خروجی داده می شود.
    
    در صورتی که همه ملیت ها قابل رزرو باشند کلمه All در این لیست خروجی داده میشود.
    
    نکته ی مهمی که باید توجه داشت اینکه لیست ملیت های ممنوعه به لیست ملیت های قابل رزرو ارجحیت دارد و جهت فهمیدن اینکه یک ملیت آیا قابل پذیرش هست یا خیر باید اول لیست ملیت های ممنوعه بررسی شود. به عنوان مثال اگر در لیست ملیت های قابل رزرو کلمه All به معنی پذیرش همه ملیت ها وجود داشته باشه ولی در لیست ملیت های ممنوعه در زمان رزرو ملیت AF (افغانستان) وجود داشته باشد، این بدین معنی است که ملیت AF قابل پذیرش نمی باشد.
  - FlightList.FlightClassList.ProhibitedNationalityList
    
    List of string
    
    لیست ملیت های ممنوعه در زمان رزرو
    
    کد 2 کاراکتری کشور ملیت هایی که مجاز به رزرو نمی باشند در این لیست خروجی داده می شود.
    
    نمونه کد سی شارپ که توسط آن می توان مجاز یا ممنوع بودن یک ملیت در زمان رزرو را بررسی کرد:
    
    public bool IsNationalityPermitted( string nationality, List<string> permittedNationalityList, List<string> prohibitedNationalityList) { if (prohibitedNationalityList.Contains(nationality)) { return false; } if (permittedNationalityList.Contains("All")) { return true; } return permittedNationalityList.Contains(nationality); }
RoundTripSearchRequiredList

list of RoundTripSearchRequired

پروازهایی که متد GetAvailableOneWayFlights برمی‌گرداند، همیشه به صورت یک‌طرفه قابل رزرو هستند.

اما برخی از کلاس‌های نرخی به دلیل محدودیت‌های نرخ‌گذاری (مثلاً تخفیف‌های ویژه یا قوانین خاص بلیت‌های دوطرفه)، قابل رزرو به صورت دوطرفه و ترکیبی نیستند.

فیلد RoundTripSearchRequiredList شامل لیستی از مسیرها و تاریخ‌ها است که در آن‌ها برای رزرو دوطرفه نباید از ترکیب نتایج همین متد استفاده کنید و باید حتماً متد SearchByRouteAndDate را صدا بزنید.

نحوه استفاده در سمت کلاینت

قبل از ترکیب پروازهای دریافتی از یک تأمین‌کننده برای رزرو دوطرفه:
1. فیلد RoundTripSearchRequiredList را بررسی کنید.
2. اگر مسیر و تاریخ مورد نظر مسافر در این لیست وجود داشت:
  - اجازه ندارید پروازهای مربوط به آن مسیر/تاریخ را که از GetAvailableOneWayFlights گرفته‌اید با هم ترکیب کرده و دوطرفه رزرو کنید.
  - در این حالت برای دریافت دیتای معتبر دوطرفه، باید از متد SearchByRouteAndDate استفاده کنید.
3. اگر مسیر و تاریخ در لیست نبود، ترکیب پروازهای این متد برای رزرو دوطرفه بلامانع است.
نکته درباره تأمین‌کنندگان مختلف

بررسی فیلد RoundTripSearchRequiredList فقط زمانی لازم است که پرواز رفت و برگشت هر دو از یک تأمین‌کننده انتخاب شوند.

اگر پرواز رفت از یک تأمین‌کننده و پرواز برگشت از تأمین‌کننده دیگری باشد:
- این محدودیت اعمال نمی‌شود.
- نیازی به بررسی فیلد RoundTripSearchRequiredList ندارید.
- چون از دید هر تأمین‌کننده، فقط یک پرواز یک‌طرفه رزرو می‌شود، داده‌های متد GetAvailableOneWayFlights برای هر کدام معتبر است.
نکته درباره آیتم های تکراری

ممکن است در طول فرآیند صفحه‌بندی، آیتم های تکراری در RoundTripSearchRequiredList صفحات مختلف بازگردانده شوند. برای مثال، آیتمی که در صفحه اول دریافت شده، ممکن است مجدداً در صفحه دوم نیز تکرار شود. مدیریت و حذف این موارد بر عهده کلاینت است.

جهت مشاهده پیاده‌سازی این فرآیند، به بخش «نمونه کد» که در ادامه آمده است مراجعه کنید.

+ نمایش ویژگی‌های زیرمجموعه
- RoundTripSearchRequiredList.Origin
  
  string
  
  کد یاتای سه حرفی فرودگاه مبدا
- RoundTripSearchRequiredList.Destination
  
  string
  
  کد یاتای سه حرفی فرودگاه مقصد
- RoundTripSearchRequiredList.Date
  
  string
  
  تاریخ پرواز با فرمت yyyy-MM-dd به زمان محلی مبدا
نمونه کد (pseudo code) بابت بررسی ترکیب پذیر بودن دو پرواز
```
private bool IsCombinable(
    List<ApiResponseModel.RoundTripSearchRequired> departingRoundTripSearchRequired,
    List<ApiResponseModel.RoundTripSearchRequired> returningRoundTripSearchRequired,
    YourModel.Flight departingFlight,
    YourModel.Flight returningFlight)
{
    // ۱. اگر تأمین‌کننده‌ها متفاوت باشند، طبق مستندات رزرو بلامانع است
    if (departingFlight.Supplier != returningFlight.Supplier)
    {
        return true;
    }

    // ۲. بررسی محدودیت برای پرواز رفت
    bool isDepartingRestricted = departingRoundTripSearchRequired.Any(x =>
        x.Origin == departingFlight.Origin &&
        x.Destination == departingFlight.Destination &&
        x.Date == departingFlight.DepartureDate);

    if (isDepartingRestricted) return false;

    // ۳. بررسی محدودیت برای پرواز برگشت
    bool isReturningRestricted = returningRoundTripSearchRequired.Any(x =>
        x.Origin == returningFlight.Origin &&
        x.Destination == returningFlight.Destination &&
        x.Date == returningFlight.DepartureDate);

    if (isReturningRestricted) return false;

    return true;
}
```

Sample Response

{
    "CurrencyCode": "IRR",
    "FlightList": [
        {
            "FlightNumber": "111",
            "DepartureDateTime": "2026-05-27 12:00",
            "Origin": "MHD",
            "Destination": "THR",
            "Aircraft": "100",
            "ArrivalDateTime": "2026-05-27 13:10",
            "Duration": 70,
            "Airline": "QB",
            "Remarks": "",
            "Source": "Owned",
            "Stop1": null,
            "Stop2": null,
            "FlightClassList": [
                {
                    "CabinType": "Economy",
                    "BookingCode": "Y",
                    "FareName": "API THR-KIH-37",
                    "AvailableSeat": 9,
                    "AdultFare": {
                        "BaseFare": 55782780.00,
                        "Tax": 0.0,
                        "TotalFare": 55782780.00,
                        "Commission": 0.0,
                        "Markup": 0.0,
                        "Payable": 55782780.00
                    },
                    "ChildFare": {
                        "BaseFare": 55782780.00,
                        "Tax": 0.0,
                        "TotalFare": 55782780.00,
                        "Commission": 0.0,
                        "Markup": 0.0,
                        "Payable": 55782780.00
                    },
                    "InfantFare": {
                        "BaseFare": 10000000.00,
                        "Tax": 0.0,
                        "TotalFare": 10000000.00,
                        "Commission": 0.0,
                        "Markup": 0.0,
                        "Payable": 10000000.00
                    },
                    "AdultFreeBaggage": {
                        "CheckedBaggageQuantity": 2,
                        "CheckedBaggageTotalWeight": 20,
                        "HandBaggageQuantity": 1,
                        "HandBaggageTotalWeight": 5
                    },
                    "ChildFreeBaggage": {
                        "CheckedBaggageQuantity": 2,
                        "CheckedBaggageTotalWeight": 20,
                        "HandBaggageQuantity": 1,
                        "HandBaggageTotalWeight": 5
                    },
                    "InfantFreeBaggage": {
                        "CheckedBaggageQuantity": 0,
                        "CheckedBaggageTotalWeight": 0,
                        "HandBaggageQuantity": 0,
                        "HandBaggageTotalWeight": 0
                    },
                    "CancelationPolicyList": [
                        {
                            "Culture": "en-US",
                            "Text": "The cancellation penalty from the time of ticket issuance until (12:00 noon), 3 days before the flight: 30%\r\nThe cancellation penalty from (12:00 noon), 3 days before the flight until (12:00 noon), 2 days before the flight: 40%\r\nThe cancellation penalty from (12:00 noon), 2 days before the flight until (12:00 noon), 1 days before the flight: 40%\r\nThe cancellation penalty from (12:00 noon), 1 days before the flight until 2 hours before the flight: 60%\r\nThe cancellation penalty from 2 hours before the flight onwards: 70% (No-Show)"
                        },
                        {
                            "Culture": "fa-IR",
                            "Text": "جريمه استرداد از زمان صدور بليت تا ساعت 12 ظهر 3 روز قبل از پرواز 30 درصد مي باشد.\r\nجريمه استرداد از ساعت 12 ظهر 3 روز قبل از پرواز تا ساعت 12 ظهر 2 روز قبل از پرواز 40 درصد مي باشد.\r\nجريمه استرداد از ساعت 12 ظهر 2 روز قبل از پرواز تا ساعت 12 ظهر 1 روز قبل از پرواز 40 درصد مي باشد.\r\nجريمه استرداد از ساعت 12 ظهر 1 روز قبل از پرواز تا 2 ساعت قبل از پرواز 60 درصد مي باشد.\r\nجريمه استرداد از 2 ساعت قبل از پرواز به بعد 70 درصد مي باشد (NoShow)."
                        }
                    ],
                    "PermittedNationalityList": ["All"],
                    "ProhibitedNationalityList": [],
                    "TemporaryProperty_DoNotUseIt_HasBookingPolicy": false
                }
            ]
        }
        // ... بیشتر پروازها
    ],
    "RoundTripSearchRequiredList": [
        {
            "Origin": "SAW",
            "Destination": "IKA",
            "Date": "2026-05-27"
        },
        {
            "Origin": "NJF",
            "Destination": "IKA",
            "Date": "2026-05-27"
        }
        // ... بیشتر مسیرها
    ],
    "HasNextPage": false
}

صفحه قبلی

صفحه بعدی

لیست سرویس‌ها

متد GetAvailableOneWayFlights

Request Parameters

Sample Request

Response Parameters

Sample Response