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

متد Book

Download Markdown for LLM

این متد جهت رزرو هتل مورد استفاده قرار میگیرد.


API Endpoint

POST https://{SupplierWebsiteUrl}/api/Partners/Hotel/Booking/V5/Book

Request Parameters

  • Username

    string

    required

    نام کاربری

  • Password

    string

    required

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

  • LockId

    number

    required

    شناسه قفل که در مرحله قبلی و با فراخوانی متد Lock دریافت نموده اید.

  • RoomList

    complex type

    required

    لیست اتاق ها و اطلاعات مسافران مربوط به هر اتاق

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

    • RoomList.AdultGuestList

      complex type

      required

      لیست میهمانان بزرگسال

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

      • RoomList.AdultGuestList.Title

        string

        required

        عنوان جنسیت میهمان که باید یکی از مقادیر MR یا MS باشد.

      • RoomList.AdultGuestList.FirstName

        string

        required

        نام میهمان

      • RoomList.AdultGuestList.LastName

        string

        required

        نام خانوادگی میهمان

      • RoomList.AdultGuestList.BirthDate

        string

        optional/conditional

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

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

      • RoomList.AdultGuestList.IranianNationalId

        string

        optional/conditional

        اطلاعات مربوط به کد ملی میهمان.

        در حالتی که میهمان ایرانی باشد و هتل نیز داخلی باشد، باید مقدار این فیلد را پر نمایید. در غیر این صورت باید فیلد Passport را پر نمایید. در غیر این صورت سیستم درخواست شما را reject خواهد کرد.

      • RoomList.AdultGuestList.Passport

        complex type

        optional/conditional

        اطلاعات مربوط به گذرنامه میهمان.

        زمانی که میهمان ایرانی باشد و هتل خارجی باشد یا در حالتی که مسافر غیر ایرانی باشد، باید این فیلد را پر نمایید. در غیر این صورت سیستم درخواست شما را reject خواهد کرد.

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

        • RoomList.AdultGuestList.Passport.Number

          string

          required

          شماره گذرنامه میهمان

        • RoomList.AdultGuestList.Passport.ExpiryDate

          string

          required

          تاریخ انقضا گذرنامه با فرمت yyyy-MM-dd و به صورت میلادی.

        • RoomList.AdultGuestList.Passport.NationalityCountryCode

          string

          required

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

          جهت مشاهده کد ISO کشور ها اینجا کلیک نمایید.

          به عنوان مثال برای ایران می توانید یکی از مقدارهای IR یا IRN را وارد نمایید.

        • RoomList.AdultGuestList.Passport.PlaceOfIssueCountryCode

          string

          required

          کد ISO دو حرفی یا سه حرفی محل صدور گذرنامه میهمان

          جهت مشاهده کد ISO کشور ها اینجا کلیک نمایید.

          به عنوان مثال برای ایران می توانید یکی از مقدارهای IR یا IRN را وارد نمایید.

    • RoomList.ChildGuestList

      string

      optional

      لیست میهمانان کودک

      ساختار آن شبیه به AdultGuestList می باشد

      نکته: با توجه به پذیرش رایگان نوزاد (سن کمتر از 2 سال) در زمان ورود به هتل، اطلاعات نوزاد را ارسال نفرمایید.

  • MobileNumber

    string

    required

    شماره تلفن همراه میهمان.

    شماره تلفن همراه باید به صورت کامل به همراه کد کشور وارد شود. به عنوان مثال فرمت زیر صحیح می باشد.

    +989352283333

  • Email

    string

    required

    آدرس ایمیل میهمان.

  • TotalPayable

    decimal

    required

    مبلغ کل رزرو.

    برای جلوگیری از خطاهای احتمالی ما در هنگام رزرو با دریافت این فیلد check price انجام می دهیم، بدین شکل که اگر مبلغ ارسالی از سمت شما با مبلغ سیستم یکی نباشد، درخواست شما reject خواهد شد.

    این فیلد مجموع فیلد Room_NetPrice_TaxIncluded (به علاوه مجموع Extrabed_NetPrice_TaxIncluded در صورت نیاز به تخت اضافه) که در مراحل availability دریافت نموده اید می باشد.

  • YourLocalInventoryPnr

    string

    optional

    رفرنس سیستم داخلی شما.

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

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

    1. در پیگیری های بعدی با استفاده از رفرنس خود شما، میتوانید پیگیری های مربوط به یک رزرو را انجام دهید.
    2. از خطر صدور تکراری رزرو جلوگیری خواهد شد

    منحصر به فرد بودن YourLocalInventoryPnr در وب سرویس های پرواز و هتل و تور سپهر به صورت یکپارچه چک می شود. به عنوان مثال اگر شما یک رفرنس را هم به وب سرویس پرواز و هم وب سرویس هتل ارسال نمایید، سیستم تنها اجازه رزرو پرواز را خواهد داد و درخواست دوم خطا برگشت میدهد. بنابراین اگر شما با یک حساب کاربری به صورت همزمان از وب سرویس پرواز یا هتل یا تور استفاده می نمایید باید دقت نموده که YourLocalInventoryPnr که در تمام این وب سرویس ها منحصر به فرد (Unique) باشد را ارسال نمایید.

  • IncomingTransfer

    complex type

    optional

    اطلاعات مربوط به ترانسفر ورودی میهمان

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

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

    • IncomingTransfer.FlightTransfer

      complex type

      optional

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

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

      • IncomingTransfer.FlightTransfer.FlightNumber

        string

        optional

        شماره پرواز

      • IncomingTransfer.FlightTransfer.DepartureTime

        string

        optional

        زمان حرکت پرواز از مبدا

      • IncomingTransfer.FlightTransfer.OriginCity

        string

        optional

        شهر مبدا پرواز

      • IncomingTransfer.FlightTransfer.AirlineName

        string

        optional

        نام ایرلاین

    • IncomingTransfer.TrainTransfer

      complex type

      optional

      در صورتی که میهمان به وسیله قطار به شهر هتل مسافرت می کند، اطلاعات مربوط به آن را در این فیلد ارسال نمایید.

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

      • IncomingTransfer.TrainTransfer.TrainNumber

        string

        optional

        شماره حرکت قطار

      • IncomingTransfer.TrainTransfer.ArrivalTime

        string

        optional

        زمان رسیدن به مقصد

      • IncomingTransfer.TrainTransfer.OriginCity

        string

        optional

        شهر مبدا قطار

      • IncomingTransfer.TrainTransfer.CarrierName

        string

        optional

        نام شرکت ارائه دهنده قطار

    • IncomingTransfer.BusTransfer

      complex type

      optional

      در صورتی که میهمان به وسیله اتوبوس به شهر هتل مسافرت می کند، اطلاعات مربوط به آن را در این فیلد ارسال نمایید.

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

      • IncomingTransfer.BusTransfer.Terminal

        string

        optional

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

      • IncomingTransfer.BusTransfer.ArrivalTime

        string

        optional

        زمان رسیدن به مقصد

      • IncomingTransfer.BusTransfer.OriginCity

        string

        optional

        شهر مبدا

      • IncomingTransfer.BusTransfer.CarrierName

        string

        optional

        نام شرکت ارائه دهنده

  • OutgoingTransfer

    complex type

    optional

    اطلاعات مربوط به ترانسفر خروج میهمان

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

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

    • OutgoingTransfer.FlightTransfer

      complex type

      optional

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

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

      • OutgoingTransfer.FlightTransfer.FlightNumber

        string

        optional

        شماره پرواز

      • OutgoingTransfer.FlightTransfer.DepartureTime

        string

        optional

        زمان پرواز

    • OutgoingTransfer.TrainTransfer

      complex type

      optional

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

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

      • OutgoingTransfer.TrainTransfer.TrainNumber

        string

        optional

        شماره حرکت قطار

      • OutgoingTransfer.TrainTransfer.DepartureTime

        string

        optional

        زمان حرکت قطار

    • OutgoingTransfer.BusTransfer

      complex type

      optional

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

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

      • OutgoingTransfer.BusTransfer.Terminal

        string

        optional

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

      • OutgoingTransfer.BusTransfer.DepartureTime

        string

        optional

        زمان حرکت

  • Remarks

    string

    optional

    ملاحظات


Sample Request

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

{
  "Username": "testdev1",
  "Password": "25f9e794323b453885f5181f1b624d0b",
  "LockId": 918,
  "YourLocalInventoryPnr": "3ecf7689-fe00-4bd9-abed-8a420f4b7303",
  "Email": "your-email-address@your-domain.com",
  "MobileNumber": "+989352283333",
  "Remarks": "",
  "RoomList": [
    {
      "AdultGuestList": [
        {
          "Title": "MS",
          "FirstName": "ROZA",
          "LastName": "FETANAT",
          "BirthDate": "1993-10-12",
          "IranianNationalId": "0010632832",
          "Passport": null
        },
        {
          "Title": "MR",
          "FirstName": "ZALI",
          "LastName": "ESFANDIAR",
          "BirthDate": "1993-10-12",
          "IranianNationalId": "0010820140",
          "Passport": null
        }
      ],
      "ChildGuestList": []
    },
    {
      "AdultGuestList": [
        {
          "Title": "MS",
          "FirstName": "PARNIA",
          "LastName": "IGHANI",
          "BirthDate": "1993-10-12",
          "IranianNationalId": "0012293504",
          "Passport": null
        },
        {
          "Title": "MR",
          "FirstName": "SEYED GHASEM",
          "LastName": "AZARKHAHMOGHADAM",
          "BirthDate": "1993-10-12",
          "IranianNationalId": "0011513578",
          "Passport": null
        }
      ],
      "ChildGuestList": [
        {
          "Title": "MS",
          "FirstName": "ZHINA",
          "LastName": "BAHRAMIKIA",
          "BirthDate": "2020-10-12",
          "IranianNationalId": "0011972386",
          "Passport": null
        }
      ]
    }
  ],
  "IncomingTransfer": null,
  "OutgoingTransfer": null,
  "TotalPayable": 25996500
}

نمونه درخواست شامل ترانسفر ورود و ترانسفر خروج

{
  "Username": "testdev1",
  "Password": "25f9e794323b453885f5181f1b624d0b",
  "LockId": 1143,
  "YourLocalInventoryPnr": "60a9db22-7b3d-429b-a08b-24afb1b9da20",
  "Email": "your-email-address@your-domain.com",
  "MobileNumber": "+989352283333",
  "Remarks": "",
  "RoomList": [
    {
      "AdultGuestList": [
        {
          "Title": "MR",
          "FirstName": "MAHSHAD",
          "LastName": "ARJMANDI",
          "BirthDate": "1993-11-29",
          "IranianNationalId": "0011333235",
          "Passport": null
        },
        {
          "Title": "MR",
          "FirstName": "ROJIA",
          "LastName": "NIKKHAH ESHGHI",
          "BirthDate": "1993-11-29",
          "IranianNationalId": "0012081671",
          "Passport": null
        }
      ],
      "ChildGuestList": []
    }
  ],
  "IncomingTransfer": {
    "FlightTransfer": {
      "FlightNumber": "7057",
      "DepartureTime": "18:30",
      "OriginCity": "tehran",
      "AirlineName": "Kish air"
    },
    "TrainTransfer": null,
    "BusTransfer": null
  },
  "OutgoingTransfer": {
    "FlightTransfer": {
      "FlightNumber": "7058",
      "DepartureTime": "12:15"
    },
    "TrainTransfer": null,
    "BusTransfer": null
  },
  "TotalPayable": 9810000
}

Response Parameters

  • Pnr

    string

    رفرنس رزرو که 6 کاراکتر و ترکیبی از حروف و اعداد می باشد.


نکات مهم

اگر در زمان رزرو با خطای Time out مواجه شدید یا هیچ جوابی از سمت سپهر دریافت نکردید، می بایست حتما وضعیت رزرو را در سایت تامین کننده بررسی نمایید. زیرا که دریافت نکردن جواب الزاما به معنی صادر نشدن رزرو نیست. و ممکن است سیستم سپهر رزرو را صادر کرده باشد ولی هنگام ارسال پاسخ به شما، اینترنت بین دیتاسنتر سپهر تا دیتاسنتر شما دچار اختلال گردیده و جواب به دست شما نرسیده باشد.

وضعیت رزرو را با یکی از دو روش زیر می توان بررسی نمود:

  • وارد پنل سایت تامین کننده شده و با جستجو کردن کد ملی/شماره گذرنامه یا "YourLocalInventoryPnr" وضعیت رزرو را بررسی نمایید.
  • با استفاده از وب سرویس و متد RetrieveBooking/GetStatus وضعیت رزرو را بررسی نمایید.

بدیهی است در صورت رعایت نکردن مورد فوق، هیچ گونه مسئولیتی متوجه سپهر نمی باشد.


Sample Response

{
  "Pnr": "V48T47"
}

Response common exceptions

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

ExceptionType توضیح خطا
Error1004-NoEnoughCredit باقی مانده اعتبار حساب برای انجام این رزرو کافی نیست.
Error1005-CreditDueDateReached مهلت پرداخت بدهی به اتمام رسیده است و انجام رزرو امکان پذیر نمی باشد
Error1007-DuplicateClientPnr مقداری که به عنوان YourLocalInventoryPnr ارسال شده است تکراری بوده و قبلا در سیستم ثبت شده است.
Error1010-LockReleased قفل رزرو آزاد شده است و رزرو قابل انجام شدن نیست. این اتفاق زمانی به وقوع می پیوندد که یا زمان بین قفل کردن تا فراخوانی متد Book، بیش از اندازه طولانی شده باشد و یا اینکه قفل رزرو توسط مدیر سیستم در سایت تامین کننده آزاد شده باشد.
Error1016-InvalidBirthdate تاریخ تولد مسافر غیر معتبر است. زمانی که تاریخ ارسال شده در بازه زمانی امروز تا 120 سال گذشته نباشد این خطا تولید می شود.
Error1021-PriceMismatch نرخ درخواستی شما با نرخ سیستم مطابقت ندارد.
Error1022-IpIsNotTrusted آی پی شما در سایت تامین کننده تراست نشده است. جهت تراست کردن آی پی با پشتیبانی سپهر تماس حاصل نمایید.
Error1023-InvalidCredential نام کاربری یا رمز عبور اشتباه می باشد.
Error1024-ForbiddenIp آی پی شما توسط تامین کننده مسدود شده است. جهت پیگیری موضوع با تامین کننده تماس بگیرید.
Error1028-HotelExtrabedExceeded تعداد تخت اضافه مورد نیاز برای انجام رزرو، بیش از گنجایش کلی تخت اضافه هتل می باشد. اگر دیتای availability را سمت خود cache می نمایید، برای کاهش احتمال بروز این خطا پیشنهاد می شود availability را در زمان های کوتاه تری دریافت نموده و cache خود را سریعتر بروز رسانی نمایید.
Error1030-PassportExpiryDateMaximumLimit تاریخ انقضای گذرنامه بیش از حد مجاز آن است. معمولا اکثر کشورها گذرنامه هایی با حداکثر تاریخ انقضای 10 سال صادر می کنند. البته این عدد بر اساس هر کشور ممکن است متفاوت باشد. به عنوان مثال اگر برای کشوری که گذرنامه های حداکثر 10 ساله دارد، تاریخ انقضای گذرنامه بیش از 10 سال ارسال شود، سیستم این خطا را تولید خواهد کرد.
Exception خطای نامشخص. جهت دریافت اطلاعات بیشتر باید به ErrorMessage داخل json برگشتی مراجعه نمود.