Booking

متد Lock

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

این متد را به دو روش مختلف می توان استفاده نمود:

  • روش اول: فراخوانی قبل از ورود به صفحه اطلاعات مسافر

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

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

    چالش این روش آن است که معمولا قفل کردن ظرفیت باعث ایجاد نارضایتی در سمت تامین کننده می گردد. زیرا در صورتی که شما ظرفیت هتل یک تامین کننده را قفل کرده ولی رزرو را نهایی نکنید (یعنی متد Book را فراخوانی نکنید) ممکن است ظرفیت آن تامین کننده سوخت شده و دچار خسارت مالی شود. بنابراین پیشنهاد ما این است که در صورت تمایل به استفاده متد Lock به این روش، حتما از قبل با مدیر فروش تامین کننده هماهنگی کرده و اجازه انجام آن را دریافت نمایید.

    به دلایل امنیتی، قفل کردن بیش از 4 عدد اتاق از یک نوع اتاق مجاز نمی باشد. در صورتی که حجم درخواست های شما زیاد بوده و احتمال میدهید روی یک نوع اتاق بیش از 4 عدد اتاق قفل نمایید، پیشهاد می گردد در زمان فراخوانی متد Lock در صورتی که با خطا مواجه شدید و ExceptionType خطا شامل Error1015-HotelLockCountLimit بود، عملیات رزرو را بدون قفل کردن ادامه دهید.

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

  • روش دوم: فراخوانی بعد از تکمیل دریافت اطلاعات مسافر

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

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

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

فراخوانی این متد در زمان انجام رزرو اجباری می باشد.

نکته: امکان رزرو تعداد میهمان کمتر از تعداد گنجایش میهمان اتاق وجود دارد. مثلا میتوان یک اتاق چهار تخته را برای رزرو دو میهمان انتخاب کرد و در زمان فراخوانی متد Lock و Book، فقط اطلاعات دو مسافر را ارسال نمود. تنها این نکته را در نظر داشته باشید که سیستم نرخ اتاق چهار تخته را برای رزرو شما در نظر خواهد گرفت. به بیان دیگر، در زمان رزرو یک اتاق چهار تخته، تفاوتی نمی کند که شما اطلاعات یک میهمان را ارسال نمایید یا اطلاعات چهار میهمان، سیستم در هر صورت نرخ کلی اتاق چهارتخته را برای شما محاسبه خواهد نمود.

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

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

\Hotel\Booking\V4\Lock\RequestModel

Username

string

required

نام کاربری

Password

string

required

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

CheckinDate

string

required

تاریخ ورود

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

CheckoutDate

string

required

تاریخ خروج

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

RoomList

Complex type

required

اطلاعات اتاق

RoomTypeSepehrGlobalId

number

required

شناسه منحصر به فرد مربوط به نوع اتاقی که تمایل دارید روی آن رزرو انجام پذیرد

BoardTypeCode

string

required

کد دو کاراکتری نوع بوردی که قصد رزرو بر اساس آن را دارید.

مثلا BB یا HB یا FB یا ….

AdultCount

number

required

تعداد بزرگسال

ChildAgeList

List(number)

اختیاری

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

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

مثال: در صورتی که سن کودک 4 سال و 1 روز باشد، باید عدد 5 را به عنوان سن ارسال نمایید. به بیان دیگر برای کودکی که سن آن بین 2 تا 3 سال است عدد 3 را ارسال نمایید و برای کودکی که سن آن بین 3 تا 4 سال است عدد 4 را ارسال نمایید. و برای سایر سن ها نیز با همین فرمول اطلاعات را ارسال نمایید.

در صورتی که هیچ کودکی درخواست نشده باشد، این لیست را خالی ارسال نمایید.

 

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

 

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

TotalPayable

decimal

required

مبلغ خالص کل رزرو.

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

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

Sample Request 
{
  "Username": "testdev1",
  "Password": "25f9e794323b453885f5181f1b624d0b",
  "CheckinDate": "2023-10-13",
  "CheckoutDate": "2023-10-16",
  "RoomList": [
    {
      "RoomTypeSepehrGlobalId": 5001,
      "BoardTypeCode": "FB",
      "AdultCount": 2,
      "ChildAgeList": []
    },
    {
      "RoomTypeSepehrGlobalId": 5004,
      "BoardTypeCode": "BB",
      "AdultCount": 2,
      "ChildAgeList": [
        3
      ]
    }
  ],
  "TotalPayable": 25996500
}
Response Data

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

\Hotel\Booking\V4\Lock\ResponseModel

LockId

number

شناسه مربوط به قفل

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

ExpiryInMinute

number

زمان آزاد شدن قفل به دقیقه

مدت زمانی که ظرفیت و نرخ توسط قفل برای شما نگه داشته می شود از فرمول زیر بدست می آید:

مدت زمان نگهداری قفل = 10 دقیقه + 2 دقیقه به ازای هر مسافر

به عنوان مثال برای یک رزرو 3 نفره، 16 دقیقه زمان نگه داری قفل خواهد بود.

نکته: مدت زمانی که سیستم به ازای هر مسافر در نظر میگیرد توسط تامین کننده قابل تغییر می باشد. مثلا یک تامین کننده ممکن است عدد 2 دقیقه و یک تامین کننده دیگر عدد 4 دقیقه را به ازای هر مسافر در نظر بگیرد.

Sample Response 
{
  "LockId": 918,
  "ExpiryInMinute": 25
}
Response common exceptions

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

ExceptionTypeتوضیح خطا

Error1004-NoEnoughCredit

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

Error1005-CreditDueDateReached

مهلت پرداخت بدهی به اتمام رسیده است و انجام رزرو امکان پذیر نمی باشد

Error1015-HotelLockCountLimit

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

Error1018-NoEnoughRoomAvailable

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

Error1021-PriceMismatch

نرخ درخواستی شما با نرخ سیستم مطابقت ندارد.

Error1022-IpIsNotTrusted

آی پی شما در سایت تامین کننده تراست نشده است. جهت تراست کردن آی پی با پشتیبانی سپهر تماس حاصل نمایید.

Error1023-InvalidCredential

نام کاربری یا رمز عبور اشتباه می باشد.

Error1024-ForbiddenIp

آی پی شما توسط تامین کننده مسدود شده است. جهت پیگیری موضوع با تامین کننده تماس بگیرید.

Exception

خطای نامشخص. جهت دریافت اطلاعات بیشتر باید به ErrorMessage داخل json برگشتی مراجعه نمود.