availability
متد GetCheapestPrice
کارکرد این متد، تعیین ارزانترین نرخ تور قابل ارائه برای هر هتل است.
برای اخذ نرخ و ظرفیت تورها، ابتدا لازم است این متد فراخوانی گردد و خروجی آن که شامل فهرستی از هتلها است به مسافر ارائه شود. پس از انتخاب هتل مورد نظر توسط مسافر، در گام بعدی میبایست متد GetHotelPackageList فراخوانی شده و نتایج حاصل از آن که مشتمل بر کلیه پکیجها (شامل پروازها و انواع اتاق) میباشد، به مسافر نمایش داده شود.
این متد فقط هتل ها یا انواع اتاقی را خروجی میدهد که در سیستم سپهر صحت قراداد تامین کننده با هتل مورد بررسی قرار گرفته باشد. بنابراین ممکن است خروجی این متد با هتل هایی که در سایت تامین کننده مشاهده می گردد یکسان نباشد.
API Endpoint
https://{SupplierWebsiteUrl}/api/Partners/Tour/Availability/V5/GetCheapestPrice post
Request Parameters
نمونه کلاس Request به زبان سی شارپ در پروژه Partners.Contracts (دانلود) در پوشه زیر موجود است:
\Tour\Availability\V5\GetCheapestPrice\RequestModel
Username
string
نام کاربری
در صورتی که شما یک موتور جستجو هستید و قصد فروش نداشته و فقط می خواهید اطلاعات هتل های عمومی را بدست آورید، نام کاربری را public ارسال نمایید.
Password
string
رمز عبور به صورت MD5 شده
OriginIataCode
string
کد یاتا فرودگاه شهر مبدا
DestinationIataCode
string
کد یاتا فرودگاه شهر مقصد
DepartureDate
string
تاریخ رفت
با فرمت yyyy-MM-dd و به صورت میلادی
ReturningDate
string
تاریخ برگشت
با فرمت yyyy-MM-dd و به صورت میلادی
TripType
string
این فیلد مشخص کننده نوع سفر است که می تواند شامل یکی از موارد زیر باشد:
- Roundtrip
زمانی که درخواست مسافر شامل هتل و هم پرواز رفت و هم پرواز برگشت باشد، باید این مقدار ارسال گردد. - HotelWithDepartureFlight
زمانی که درخواست مسافر فقط شامل هتل و پرواز رفت باشد، باید این مقدار ارسال گردد. - HotelWithReturningFlight
زمانی که درخواست مسافر فقط شامل هتل و پرواز برگشت باشد، باید این مقدار ارسال گردد.
RoomList
Complex type
لیستی از اتاق های درخواستی که شامل تعداد اتاق و تعداد میهمانان مقیم هر اتاق می باشد
حداکثر تعداد اتاق درخواستی 4 عدد می باشد.
AdultCount
number
تعداد میهمان بزرگسال روی این اتاق
ChildAgeList
list of numbers
لیستی از سن کودک
این لیست هم تعداد کودک و هم سن آنها را مشخص می نماید، بدین ترتیت که تعداد item های این لیست مشخص کننده تعداد کودک و مقدار هم item مشخص کننده سن کودک می باشد.
مثال: در صورتی که سن کودک 4 سال و 1 روز باشد، باید عدد 5 را به عنوان سن ارسال نمایید. به بیان دیگر برای کودکی که سن آن کمتر از 1 سال است باید عدد 1 را ارسال نمایید و برای کودکی که سن آن بین 1 تا 2 سال است باید عدد 2 را ارسال نمایید و برای کودکی که سن آن بین 2 تا 3 سال است عدد 3 را ارسال نمایید. و برای سایر سن ها نیز با همین فرمول اطلاعات را ارسال نمایید.
در صورتی که هیچ کودکی درخواست نشده باشد، این لیست را خالی ارسال نمایید.
Language
string enum
زبان برگشت پیام ها از وب سرویس که می تواند FA یا EN باشد.
در زمان هایی که وب سرویس خطایی را برمیگرداند – مثلا تکمیل ظرفیت یک پرواز – با استفاده از این فیلد می توانید زبان پیام را مشخص نمایید.
HotelSepehrGlobalId
number
در صورتی که نیاز به دریافت اطلاعات اتاق های موجود و نرخ یک هتل خاص را دارید، کد SepehrGlobalId آن هتل خاص را در این فیلد قرار دهید.
{
"UserName": "testdev1",
"Password": "25f9e794323b453885f5181f1b624d0b",
"OriginIataCode": "THR",
"DestinationIataCode": "KIH",
"DepartureDate": "2025-10-08",
"ReturningDate": "2025-10-11",
"TripType": "Roundtrip",
"RoomList": [{
"AdultCount": 2,
"ChildAgeList": []
}
],
"Language": "FA",
"HotelSepehrGlobalId": null
}
{
"UserName": "testdev1",
"Password": "25f9e794323b453885f5181f1b624d0b",
"OriginIataCode": "THR",
"DestinationIataCode": "KIH",
"DepartureDate": "2025-10-08",
"ReturningDate": "2025-10-11",
"TripType": "Roundtrip",
"RoomList": [{
"AdultCount": 2,
"ChildAgeList": []
}, {
"AdultCount": 1,
"ChildAgeList": [3]
}
],
"Language": "FA",
"HotelSepehrGlobalId": null
}
Response Data
نمونه کلاس Response به زبان سی شارپ در پروژه Partners.Contracts (دانلود) در پوشه زیر موجود است:
\Tour\Availability\V5\GetCheapestPrice\ResponseModel
CurrencyCode
string
این فیلد مشخص می کند که نرخ های برگشتی بر اساس چه ارزی می باشد.
مقدار آن بستگی به این دارد که ارز کاربر شما در سایت تامین کننده چه چیزی تعیین شده باشد. مثلا اگر کاربر شما به صورت ریالی باشد مقدار آن IRR و اگر دلاری باشد مقدار آن USD خواهد بود.
Complex type
لیست ارزانترن نرخ تور بر اساس هر هتل
سامانه سپهر، تمامی حالتهای ترکیبی هتل و پرواز مربوط به تور را محاسبه نموده و سپس ارزانترین ترکیبی را که برای یک هتل شناسایی کرده است، در این فهرست ارائه میدهد.
DepartureFlight
Complex type
اطلاعات ارزان ترین پرواز رفت که برای این هتل در محاسبات پیدا شده است.
FlightNumber
string
شماره پرواز
DepartureDateTime
string
تاریخ پرواز با فرمت yyyy-MM-dd HH:mm به زمان محلی مبدا
Origin
Complex type
فرودگاه مبدا
Code
string
کد یاتای سه حرفی فرودگاه مبدا
Terminal
string
ترمینال مبدا. در حال حاضر خالی برگشت داده میشود.
Destination
Complex type
فرودگاه مقصد
Code
string
کد یاتای سه حرفی فرودگاه مقصد
Terminal
string
ترمینال مقصد. در حال حاضر خالی برگشت داده میشود.
ArrivalDateTime
string
زمان رسیدن پرواز به مقصد با فرمت yyyy-MM-dd HH:mm به زمان محلی مقصد
Duration
number
طول مدت پرواز بر حسب دقیقه
در صورتی که در سیستم خود طول مدت پرواز را نمایش می دهید، بهتر است به جای بدست آوردن تفاوت بین DepartureDateTime و ArrivalDateTime، از مقدار این فیلد استفاده نمایید. زیرا بدست آوردن تفاوت بر اساس DepartureDateTime و ArrivalDateTime نیازمند در نظر گرفتن ناحیه زمانی مبدا و مقصد بوده و یا حتی در مواردی که مبدا و مقصد یکسان بوده ولی ساعت ها تغییر کنند (مانند اول فروردین یا اول مهرماه) بدست آوردن این تفاوت، نیازمند عملیات پیچیده است. بنابراین بهتر است از مقدار این فیلد استفاده نمایید.
Airline
string
کد یاتا ایرلاین
Remarks
string
اگر تامین کننده توضیحاتی در خصوص این پرواز ثبت کرده باشد، این توضیحات به صورت متن در این فیلد خروجی داده می شود.
عموما شما نیازی به استفاده از این فیلد نخواهید داشت و می توانید آن را نادیده بگیرید.
Stop1
Complex type
در صورتی که پرواز دارای Stop باشد، اطلاعات اولین توقف در این فیلد خروجی داده خواهد شد.
در پروزهای Stop دار، در زمان توقف، مسافر از هواپیما پیاده نشده و همچنین نیازی به جابجایی بار نیست. معمولا این گونه توقف ها بابت پیاده یا سوار کردن مسافران جدید یا سوخت گیری انجام می پذیرد. و در هر صورتی مسافران قبلی در زمان توقف در هواپیما باقی مانده و نیازی به ترک هواپیما نمی باشد.
AirportIataCode
string
کد یاتا فرودگاه محل توقف
FlightDurationUntilThisStopInMinute
number
طول مدت پرواز تا رسیدن به فرودگاه محل توقف.
مقدار این فیلد بر اساس دقیقه می باشد.
StopDurationInMinute
number
طول مدت توقف در فرودگاه
مقدار این فیلد بر اساس دقیقه می باشد.
ArrivalDateTime
string
زمان ورود به فرودگاه محل توقف
بر اساس زمان محلی و با فرمت yyyy-MM-dd HH:mm
DepartureDateTime
string
زمان خروج از فرودگاه محل توقف
بر اساس زمان محلی و با فرمت yyyy-MM-dd HH:mm
جهت بررسی این فیلد می توانید از تست سناریوهای زیر استفاده نمایید:
Stop2
Complex type
در صورتی که پرواز دارای بیش از یک Stop باشد، اطلاعات مربوط به توقف دوم توسط این فیلد خروجی داده می شود.
ساختار فرمت آن مشابه فیلد Stop1 می باشد.
جهت بررسی این فیلد می توانید از تست سناریوهای زیر استفاده نمایید:
CabinType
string
نوع کابین کلاس پروازی که می تواند یکی از موارد زیر را داشته باشد:
- Economy
- EconomyPlus
- PremiumEconomy
- Business
- BusinessComfort
- BusinessPremium
- First
BookingCode
string
معمولا ترکیب یک یا دو حرف بوده و مشخص کننده نوع BookingCode می باشد. مانند Y یا M.
طول این فیلد حداکثر 3 کاراکتر می باشد.
FareName
string
نام Fare کلاس پروازی که می تواند ترکیب طولانی از حروف و اعداد باشد مانند THRMHD137. این نام در زمان رزرو گرفتن باید ارسال شود تا مشخص کند شما می خواهید روی چه کلاس پروازی رزرو خود را انجام دهید.
طول این فیلد حداکثر 50 کاراکتر می باشد.
AdultFreeBaggage
Complex type
اطلاعات مربوط به بار مجاز یک نفر بزرگسال
CheckedBaggageQuantity
number
تعداد چمدان بار مجاز جهت قسمت بار هواپیما
CheckedBaggageTotalWeight
number
مجموع وزن بار مجاز جهت قسمت بار هواپیما
HandBaggageQuantity
number
تعداد کیف دستی قابل حمل به داخل هواپیما
HandBaggageTotalWeight
number
مجموع وزن کیف دستی قابل حمل به داخل هواپیما
ChildFreeBaggage
Complex type
اطلاعات مربوط به بار مجاز یک نفر کودک
ساختار آن شبیه به AdultFreeBaggage می باشد.
InfantFreeBaggage
Complex type
اطلاعات مربوط به بار مجاز یک نفر نوزاد
ساختار آن شبیه به AdultFreeBaggage می باشد.
ReturningFlight
complex type
اطلاعات ارزان ترین پرواز برگشت که برای این هتل در محاسبات پیدا شده است.
ساختار آن کاملا شبیه DepartureFlight می باشد.
Hotel
Complex type
اطلاعات مربوط به هتل
SepehrGlobalId
number
شناسه منحصر به فرد مربوط به این هتل در تمام سایت های سپهری
Name
string
نام هتل
RoomTypeList
Complex type
لیست انواع اتاق موجود روی این هتل
SepehrGlobalId
number
شناسه منحصر به فرد مربوط به این نوع اتاق در تمام سایت های سپهری
Name
string
عنوان نوع اتاق
BoardTypeCode
string
کد نوع بورد که یکی از موارد زیر می باشد:
- RO
مخفف Room Only و به معنی اسکان تک و بدون هیچ وعده غذایی می باشد. - SC
مخفف Self Catering می باشد و بیشتر در هتل آپارتمان ها تعریف می شود. - BB
مخفف Bed & Breakfast و به معنی اقامت با صبحانه می باشد - HB
مخفف Half Board و به معنی اقامت به همراه صبحانه و ناهار می باشد. - BD
به معنی اقامت به همراه صبحانه و شام می باشد. - BS
به معنی اقامت به همراه صبحانه و یک وعده غذایی دیگر به انتخاب مسافر (یا ناهار یا شام) می باشد. - FC
به معنی Full Board و اقامت به همراه صبحانه و ناهار و شام به صورت منوی بسته می باشد. - FB
به معنی Full Board و اقامت به همراه صبحانه و ناهار و شام به صورت منوی انتخابی می باشد. - FF
به معنی Full Board و اقامت به همراه صبحانه و ناهار و شام به صورت منوی بوفه می باشد. - AI
مخفف All Inclusive و از نظر ارائه میان وعده های غذایی بالاتر از FB می باشد. - UA
مخفف Ultra All Inclusive می باشد
AdultCount
number
تعداد میهمانان بزرگسال که طبق درخواست شما در این نوع اتاق جا داده شده است
ChildAgeList
list of numbers
سن میهمانان کودک که طبق درخواست شما در این نوع اتاق جا داده شده است
ExtrabedAssignedCount
number
تعداد تخت اضافه اختصاص شده روی این اتاق
در صورتی که اتاق گنجایش تخت اضافه داشته باشد و جهت اسکان تعداد میهمانان درخواستی شما در این نوع اتاق نیاز به تخت اضافه باشد، سیستم تعداد تخت اضافه که جهت اسکان اختصاص داده شده است را در این فیلد خروجی میدهد.
TotalFlightNetPrice
decimal
مجموع نرخ لگ های پروازی
مقدار این فیلد مورد نیاز متد Lock می باشد و کاربرد دیگری ندارد.
TotalHotelNetPrice
decimal
مجموع نرخ هتل
مقدار این فیلد مورد نیاز متد Lock می باشد و کاربرد دیگری ندارد.
TotalGrossPrice
decimal
نرخ ناخالص (قبل از کسر کمیسیون) تور
مقدار این فیلد جهت نمایش در سایت شما به مسافر کاربرد دارد. به این صورت که می توانید مقدار این فیلد را به عنوان مبلغ اولیه (قبل از اعمال شدن تخفیف) به مسافر نمایش دهید
TotalCommission
decimal
مجموع کمیسیون که در صورت رزرو به شما تعلق خواهد گرفت
TotalNetPrice
decimal
نرخ خالص (بعد از کسر کمیسیون) تور
این مبلغ در زمان رزرو در حساب بدهکاری شما منظور خواهد شد.
{
"CurrencyCode": "IRR",
"CheapestPriceList": [{
"DepartureFlight": {
"FlightNumber": "412",
"DepartureDateTime": "2025-10-08 18:00",
"Origin": {
"Code": "THR",
"Terminal": null
},
"Destination": {
"Code": "KIH",
"Terminal": null
},
"Aircraft": "AB4",
"ArrivalDateTime": "2025-10-08 19:50",
"Duration": 110,
"Airline": "NV",
"Remarks": "",
"Stop1": null,
"Stop2": null,
"CabinType": "Business",
"BookingCode": "C",
"FareName": "THRMHD1",
"AdultFreeBaggage": {
"CheckedBaggageQuantity": 0,
"CheckedBaggageTotalWeight": 0,
"HandBaggageQuantity": 0,
"HandBaggageTotalWeight": 0
},
"ChildFreeBaggage": {
"CheckedBaggageQuantity": 0,
"CheckedBaggageTotalWeight": 0,
"HandBaggageQuantity": 0,
"HandBaggageTotalWeight": 0
},
"InfantFreeBaggage": {
"CheckedBaggageQuantity": 0,
"CheckedBaggageTotalWeight": 0,
"HandBaggageQuantity": 0,
"HandBaggageTotalWeight": 0
}
},
"ReturningFlight": {
"FlightNumber": "413",
"DepartureDateTime": "2025-10-11 10:00",
"Origin": {
"Code": "KIH",
"Terminal": null
},
"Destination": {
"Code": "THR",
"Terminal": null
},
"Aircraft": "AB4",
"ArrivalDateTime": "2025-10-11 11:10",
"Duration": 70,
"Airline": "HH",
"Remarks": "",
"Stop1": null,
"Stop2": null,
"CabinType": "Economy",
"BookingCode": "Y",
"FareName": "MHD",
"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
}
},
"Hotel": {
"SepehrGlobalId": 101,
"Name": "هتل کوهستان تستي",
"RoomTypeList": [{
"SepehrGlobalId": 5004,
"Name": "دو تخته دبل",
"BoardTypeCode": "BB",
"AdultCount": 2,
"ChildAgeList": [],
"ExtrabedAssignedCount": 0
}
]
},
"TotalFlightNetPrice": 17809900.00,
"TotalHotelNetPrice": 3270000.00,
"TotalGrossPrice": 21512000.00,
"TotalCommission": 432100.0,
"TotalNetPrice": 21079900.00
}
]
}
{
"CurrencyCode": "IRR",
"CheapestPriceList": [{
"DepartureFlight": {
"FlightNumber": "412",
"DepartureDateTime": "2025-10-08 18:00",
"Origin": {
"Code": "THR",
"Terminal": null
},
"Destination": {
"Code": "KIH",
"Terminal": null
},
"Aircraft": "AB4",
"ArrivalDateTime": "2025-10-08 19:50",
"Duration": 110,
"Airline": "NV",
"Remarks": "",
"Stop1": null,
"Stop2": null,
"CabinType": "Business",
"BookingCode": "C",
"FareName": "THRMHD1",
"AdultFreeBaggage": {
"CheckedBaggageQuantity": 0,
"CheckedBaggageTotalWeight": 0,
"HandBaggageQuantity": 0,
"HandBaggageTotalWeight": 0
},
"ChildFreeBaggage": {
"CheckedBaggageQuantity": 0,
"CheckedBaggageTotalWeight": 0,
"HandBaggageQuantity": 0,
"HandBaggageTotalWeight": 0
},
"InfantFreeBaggage": {
"CheckedBaggageQuantity": 0,
"CheckedBaggageTotalWeight": 0,
"HandBaggageQuantity": 0,
"HandBaggageTotalWeight": 0
}
},
"ReturningFlight": {
"FlightNumber": "413",
"DepartureDateTime": "2025-10-11 10:00",
"Origin": {
"Code": "KIH",
"Terminal": null
},
"Destination": {
"Code": "THR",
"Terminal": null
},
"Aircraft": "AB4",
"ArrivalDateTime": "2025-10-11 11:10",
"Duration": 70,
"Airline": "HH",
"Remarks": "",
"Stop1": null,
"Stop2": null,
"CabinType": "Economy",
"BookingCode": "Y",
"FareName": "MHD",
"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
}
},
"Hotel": {
"SepehrGlobalId": 101,
"Name": "هتل کوهستان تستي",
"RoomTypeList": [{
"SepehrGlobalId": 5004,
"Name": "دو تخته دبل",
"BoardTypeCode": "BB",
"AdultCount": 2,
"ChildAgeList": [],
"ExtrabedAssignedCount": 0
}, {
"SepehrGlobalId": 5004,
"Name": "دو تخته دبل",
"BoardTypeCode": "BB",
"AdultCount": 1,
"ChildAgeList": [3],
"ExtrabedAssignedCount": 0
}
]
},
"TotalFlightNetPrice": 34014850.00,
"TotalHotelNetPrice": 6540000.00,
"TotalGrossPrice": 41203000.00,
"TotalCommission": 648150.0,
"TotalNetPrice": 40554850.00
}
]
}