مستندات وب سرویس

متد SearchByCityAndDateAndGuests

Download Markdown for LLM

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

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

تأمین‌کنندگان در سیستم رزرواسیون سپهر می‌توانند قوانینی تعریف کنند که بر اساس آن‌ها، تاریخ ورود (Check-in) و تاریخ خروج (Check-out) در فرآیند بررسی Availability دارای اهمیت ویژه‌ای می‌شود. به این معنا که صرفاً موجود بودن یا نبودن اتاق ملاک نیست و ترکیب تاریخ‌های ورود و خروج نیز می‌تواند مستقیماً بر امکان‌پذیری رزرو تأثیر بگذارد.

برای مثال، ممکن است سیستم سپهر برای تاریخ ورود ۵ شهریور و تاریخ خروج ۸ شهریور پاسخ «عدم موجودی» برگرداند، اما برای همان تاریخ ورود و با تاریخ خروج ۹ شهریور، رزرو را تأیید کند.

در نتیجه، پاسخ دریافتی از این متد صرفاً برای تاریخ‌های Check-in و Check-out ارسال‌شده در درخواست معتبر است و امکان تعمیم آن به سایر تاریخ‌های ورود یا خروج وجود ندارد.

سؤال:
آیا امکان دارد برای یک رزرو، بخشی از شب‌ها از یک تأمین‌کننده و بخش دیگر از تأمین‌کننده‌ای متفاوت رزرو شود؟

پاسخ:
این موضوع به قوانین و محدودیت‌های تعریف‌شده توسط هر تأمین‌کننده بستگی دارد.

توضیح با مثال:
فرض کنید یک هتل (مثلاً هتل آرامیس پلاس کیش) توسط چند تأمین‌کننده مختلف ارائه می‌شود و هر تأمین‌کننده ممکن است برای شب‌های خاصی نرخ متفاوتی داشته باشد.
برای نمونه، شما قصد دارید یک رزرو ۴ شبه انجام دهید:

  • تأمین‌کننده اول برای دو شب اول نرخ ارزان‌تری ارائه می‌دهد.
  • تأمین‌کننده دوم برای شب سوم و چهارم نرخ مناسب‌تری دارد.
  • نتیجه‌ی درخواست availability اولیه نشان می‌دهد که هر دو تأمین‌کننده برای هر چهار شب موجودی دارند.

در این شرایط ممکن است تصمیم بگیرید:

  • دو شب اول را از تأمین‌کننده اول
  • و دو شب بعدی را از تأمین‌کننده دوم رزرو کنید.

نکته‌ی مهم:
با وجود اینکه هر دو تأمین‌کننده موجودی چهار شب را اعلام کرده‌اند، ممکن است به دلیل محدودیت‌هایی که تأمین‌کنندگان روی تاریخ ورود (Check-in) و تاریخ خروج (Check-out) اعمال می‌کنند، امکان رزرو بخشی از این بازه (مثلاً فقط دو شب از چهار شب) وجود نداشته باشد. رزرو اتاق‌ها به تاریخ ورود و خروج بسیار حساس است.

اقدام صحیح برای بررسی امکان رزرو:
برای اطمینان از امکان انجام این نوع رزرو، لازم است:

  1. یک درخواست availability برای دو شب اول به تأمین‌کننده اول ارسال شود.
  2. یک درخواست availability جداگانه برای شب سوم و چهارم به تأمین‌کننده دوم ارسال گردد.
  3. تنها در صورتی که هر دو تأمین‌کننده موجودی را تأیید کنند، می‌توان رزروها را به‌صورت جداگانه ثبت نمود.

نکته‌ی فنی مهم:
در صورتی که رزرو از دو تأمین‌کننده مختلف انجام شود، به دلیل استقلال نرم‌افزار و سرور هر تأمین‌کننده، این رزروها در دو تراکنش مجزا ثبت می‌شوند.
در نتیجه، این احتمال وجود دارد که:

  • رزرو دو شب اول با موفقیت انجام شود،
  • اما رزرو دو شب بعدی به دلیل بروز خطا ناموفق باشد.

بنابراین مدیریت خطا و بررسی وضعیت هر دو رزرو به‌صورت مستقل ضروری است.


API Endpoint

POST https://{SupplierWebsiteUrl}/api/Partners/Hotel/Availability/V4/SearchByCityAndDateAndGuests

Request Parameters

  • Username

    string

    required

    نام کاربری

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

  • Password

    string

    required

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

  • CityIataCode

    string

    required

    کد یاتا شهر مورد نظر

    در حال حاضر وب سرویس هتل سپهر بر اساس کد یاتا فرودگاه آن شهر کار می کند. در نسخه های بعدی وب سرویس، امکان جستجو روی شهرهایی که فاقد کد یاتا هستند نیز اضافه خواهد گردید.

  • CheckinDate

    string

    required

    تاریخ ورود

    با فرمت yyyy-MM-dd و به صورت میلادی

  • CheckoutDate

    string

    required

    تاریخ خروج

    با فرمت yyyy-MM-dd و به صورت میلادی

  • RoomList

    Complex type

    required

    لیستی از اتاق های درخواستی که شامل تعداد اتاق و تعداد میهمانان مقیم هر اتاق می باشد

    حداکثر تعداد اتاق درخواستی 4 عدد می باشد.

    + نمایش ویژگی‌های زیرمجموعه

    • RoomList.AdultCount

      number

      required

      تعداد میهمان بزرگسال روی این اتاق

    • RoomList.ChildAgeList

      list of numbers

      optional

      لیستی از سن کودک

      این پارامتر برای مشخص‌کردن تعداد کودکان و سن هر کودک استفاده می‌شود.
      به این صورت که:

      • تعداد آیتم‌های موجود در لیست، نشان‌دهنده تعداد کودکان است.
      • مقدار هر آیتم، سن همان کودک را مشخص می‌کند.

      نحوه محاسبه سن:

      سن کودک باید به صورت عدد صحیح رو به بالا (Ceiling) ارسال شود. به عبارت دیگر:

      • کمتر از ۱ سال → 1
      • بین ۱ تا کمتر از ۲ سال → 2
      • بین ۲ تا کمتر از ۳ سال → 3
      • …
      • ۴ سال و ۱ روز → 5

      مثال:

      اگر دو کودک با سن‌های زیر وجود داشته باشند:

      • کودک اول: ۲ سال و ۶ ماه
      • کودک دوم: ۴ سال و ۱ روز

      مقدار ارسالی باید به صورت زیر باشد:
      ChildAgeList = [3, 5]

  • HotelSepehrGlobalId

    number

    optional

    در صورتی که نیاز به دریافت اطلاعات اتاق های موجود و نرخ یک هتل خاص را دارید، کد SepehrGlobalId آن هتل خاص را در این فیلد قرار دهید.


Sample Request

نمونه درخواست - یک اتاق - دو بزرگسال

{
    "Username": "testdev1",
    "Password": "25f9e794323b453885f5181f1b624d0b",
    "CityIataCode": "KIH",
    "CheckinDate": "2026-05-22",
    "CheckoutDate": "2026-05-25",
    "RoomList": [{
            "AdultCount": 2,
            "ChildAgeList": []
        }
    ],
    "HotelSepehrGlobalId": null
}

نمونه درخواست - دو اتاق - سه بزرگسال - یک کودک 3 ساله

{
    "Username": "testdev1",
    "Password": "25f9e794323b453885f5181f1b624d0b",
    "CityIataCode": "KIH",
    "CheckinDate": "2026-05-22",
    "CheckoutDate": "2026-05-25",
    "RoomList": [{
            "AdultCount": 2,
            "ChildAgeList": []
        }, {
            "AdultCount": 1,
            "ChildAgeList": [3]
        }
    ],
    "HotelSepehrGlobalId": null
}

Response Parameters

  • CurrencyCode

    string

    این فیلد مشخص می کند که نرخ های برگشتی بر اساس چه ارزی می باشد.

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

  • HotelOptionList

    Complex type

    لیست هتل های قابل رزرو

    + نمایش ویژگی‌های زیرمجموعه

    • HotelOptionList.SepehrHotelGlobalId

      number

      شناسه منحصر به فرد مربوط به این هتل در تمام سایت های سپهری

    • HotelOptionList.Name

      string

      نام هتل

    • HotelOptionList.RoomTypeList

      Complex type

      لیست انواع اتاق موجود روی این هتل

      + نمایش ویژگی‌های زیرمجموعه

      • HotelOptionList.RoomTypeList.SepehrGlobalId

        number

        شناسه منحصر به فرد مربوط به این نوع اتاق در تمام سایت های سپهری

      • HotelOptionList.RoomTypeList.Name

        string

        عنوان نوع اتاق

      • HotelOptionList.RoomTypeList.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 می باشد

      • HotelOptionList.RoomTypeList.AdultCount

        number

        تعداد میهمانان بزرگسال که طبق درخواست شما در این نوع اتاق جا داده شده است

      • HotelOptionList.RoomTypeList.ChildAgeList

        list of numbers

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

      • HotelOptionList.RoomTypeList.ExtrabedAssignedCount

        number

        تعداد تخت اضافه اختصاص شده روی این اتاق

        در صورتی که اتاق گنجایش تخت اضافه داشته باشد و جهت اسکان تعداد میهمانان درخواستی شما در این نوع اتاق نیاز به تخت اضافه باشد، سیستم تعداد تخت اضافه که جهت اسکان اختصاص داده شده است را در این فیلد خروجی میدهد.

    • HotelOptionList.AmenityList

      Complex type

      لیست خدمات ارائه شده روی این هتل

      + نمایش ویژگی‌های زیرمجموعه

      • HotelOptionList.AmenityList.SepehrGlobalId

        number

        شناسه منحصر به فرد مربوط به این خدمت در تمام سایت های سپهری

      • HotelOptionList.AmenityList.Name

        string

        عنوان خدمت

      • HotelOptionList.AmenityList.Quantity

        number

        تعداد خدمت ارائه شده

    • HotelOptionList.TotalGrossPrice

      decimal

      نرخ ناخالص (قبل از کسر کمیسیون)

      مقدار این فیلد جهت نمایش در سایت شما به مسافر کاربرد دارد. به این صورت که می توانید مقدار این فیلد را به عنوان مبلغ اولیه (قبل از اعمال شدن تخفیف) به مسافر نمایش دهید

    • HotelOptionList.TotalCommission

      decimal

      مجموع کمیسیون که در صورت رزرو به شما تعلق خواهد گرفت

    • HotelOptionList.TotalNetPrice

      decimal

      نرخ خالص (بعد از کسر کمیسیون)

      این مبلغ در زمان رزرو در حساب بدهکاری شما منظور خواهد شد.


Sample Response

نمونه پاسخ - یک اتاق - دو بزرگسال

{
    "HotelOptionList": [{
            "SepehrHotelGlobalId": 101,
            "Name": "هتل کوهستان تستي",
            "RoomTypeList": [{
                    "SepehrGlobalId": 5004,
                    "Name": "دو تخته دبل",
                    "BoardTypeCode": "BB",
                    "AdultCount": 2,
                    "ChildAgeList": [],
                    "ExtrabedAssignedCount": 0
                }
            ],
            "AmenityList": [{
                    "SepehrGlobalId": 102,
                    "Name": "استخر روباز",
                    "Quantity": 6
                }, {
                    "SepehrGlobalId": 100,
                    "Name": "استقبال فرودگاهی",
                    "Quantity": 6
                }, {
                    "SepehrGlobalId": 103,
                    "Name": "بیمه مسافرتی",
                    "Quantity": 2
                }
            ],
            "TotalGrossPrice": 55810000.00,
            "TotalCommission": 0.0,
            "TotalNetPrice": 59950000.00
        },
        // ... بیشتر هتل‌ها و اتاق‌ها
    ],
    "CurrencyCode": "IRR"
}

نمونه پاسخ - دو اتاق - سه بزرگسال - یک کودک 3 ساله

{
    "HotelOptionList": [{
            "SepehrHotelGlobalId": 101,
            "Name": "هتل کوهستان تستي",
            "RoomTypeList": [{
                    "SepehrGlobalId": 5004,
                    "Name": "دو تخته دبل",
                    "BoardTypeCode": "BB",
                    "AdultCount": 2,
                    "ChildAgeList": [],
                    "ExtrabedAssignedCount": 0
                }, {
                    "SepehrGlobalId": 5004,
                    "Name": "دو تخته دبل",
                    "BoardTypeCode": "BB",
                    "AdultCount": 1,
                    "ChildAgeList": [3],
                    "ExtrabedAssignedCount": 0
                }
            ],
            "AmenityList": [{
                    "SepehrGlobalId": 102,
                    "Name": "استخر روباز",
                    "Quantity": 12
                }, {
                    "SepehrGlobalId": 100,
                    "Name": "استقبال فرودگاهی",
                    "Quantity": 12
                }, {
                    "SepehrGlobalId": 103,
                    "Name": "بیمه مسافرتی",
                    "Quantity": 4
                }
            ],
            "TotalGrossPrice": 111620000.00,
            "TotalCommission": 0.0,
            "TotalNetPrice": 119900000.00
        },
        // ... بیشتر هتل‌ها و اتاق‌ها
    ],
    "CurrencyCode": "IRR"
}