Booking

متد Book

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

API Endpoint
https://{SupplierWebsiteUrl}/api/Partners/Hotel/Booking/V4/Book post
Request Parameters

نمونه کلاس Request به زبان سی شارپ در پروژه Partners.Contracts (دانلود) در پوشه زیر موجود است:

\Hotel\Booking\V4\Book\RequestModel

Username

string

required

نام کاربری

Password

string

required

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

LockId

number

required

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

RoomList

complex type

required

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

AdultGuestList

complex type

required

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

Title

string

required

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

FirstName

string

required

نام میهمان

LastName

string

required

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

BirthDate

string

optional/conditional

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

 

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

IranianNationalId

string

optional/conditional

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

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

Passport

complex type

optional/conditional

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

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

Number

string

required

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

ExpiryDate

string

required

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

NationalityCountryCode

string

required

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

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

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

PlaceOfIssueCountryCode

string

required

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

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

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

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

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

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

FlightTransfer

complex type

optional

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

FlightNumber

string

optional

شماره پرواز

DepartureTime

string

optional

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

OriginCity

string

optional

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

AirlineName

string

optional

نام ایرلاین

TrainTransfer

complex type

optional

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

TrainNumber

string

optional

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

ArrivalTime

string

optional

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

OriginCity

string

optional

شهر مبدا قطار

CarrierName

string

optional

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

BusTransfer

complex type

optional

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

Terminal

string

optional

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

ArrivalTime

string

optional

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

OriginCity

string

optional

شهر مبدا

CarrierName

string

optional

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

OutgoingTransfer

complex type

optional

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

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

FlightTransfer

complex type

optional

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

FlightNumber

string

optional

شماره پرواز

DepartureTime

string

optional

زمان پرواز

TrainTransfer

complex type

optional

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

TrainNumber

string

optional

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

DepartureTime

string

optional

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

BusTransfer

complex type

optional

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

Terminal

string

optional

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

DepartureTime

string

optional

زمان حرکت

Remarks

string

optional

ملاحظات

نمونه درخواست شامل دو اتاق، اتاق اول شامل دو بزرگسال و اتاق دوم شامل دو بزرگسال و یک کودک 
{
  "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 Data

نمونه کلاس Response به زبان سی شارپ در پروژه Partners.Contracts (دانلود) در پوشه زیر موجود است:

\Hotel\Booking\V4\Book\ResponseModel

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 برگشتی مراجعه نمود.