---
title: "Lock | Booking | تور | مستندات وب سرویس سپهر"
---
# booking



## متد Lock

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

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

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

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

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

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

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

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

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

<br>

API Endpoint

```http
POST https://{SupplierWebsiteUrl}/api/Partners/Tour/Booking/V3/Lock
```

<br>

## Request Parameters

- `Username`

  string

  required

  نام کاربری

- `Password`

  string

  required

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

- `DepartureSegment`

  Complex type

  required

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

  - `DepartureSegment.FlightNumber`

    string

    شماره پرواز

  - `DepartureSegment.FlightDate`

    string

    زمان پرواز با فرمت yyyy-MM-dd HH:mm به صورت میلادی.

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

  - `DepartureSegment.OriginIataCode`

    string

    کد یاتا فرودگاه مبدا

  - `DepartureSegment.DestinationIataCode`

    string

    کد یاتا فرودگاه مقصد

  - `DepartureSegment.FareName`

    string

    نام Fare یا در واقع همان کلاس پروازی که می خواهید رزرو روی آن انجام شود.

- `ReturningSegment`

  Complex type

  required

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

  ساختار آن کاملا شبیه DepartureSegment می باشد.

- `CheckinDate`

  string

  required

  تاریخ ورود به هتل

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

- `CheckoutDate`

  string

  required

  تاریخ خروج از هتل

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

- `RoomList`

  Complex type

  required

  اطلاعات اتاق

  - `RoomList.RoomTypeSepehrGlobalId`

    number

    required

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

  - `RoomList.BoardTypeCode`

    string

    required

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

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

  - `RoomList.AdultCount`

    number

    required

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

  - `RoomList.ChildAgeList`

    List(number)

    اختیاری

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

    این پارامتر برای مشخص‌کردن تعداد کودکان و سن هر کودک استفاده می‌شود.
    به این صورت که:
    - تعداد آیتم‌های موجود در لیست، نشان‌دهنده تعداد کودکان است.
    - مقدار هر آیتم، سن همان کودک را مشخص می‌کند.

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

    سن کودک باید به صورت عدد صحیح رو به بالا (Ceiling) ارسال شود. به عبارت دیگر:
    - کمتر از ۱ سال → 1
    - بین ۱ تا کمتر از ۲ سال → 2
    - بین ۲ تا کمتر از ۳ سال → 3
    - ...
    - ۴ سال و ۱ روز → 5

    مثال:

    اگر دو کودک با سن‌های زیر وجود داشته باشند:
    - کودک اول: ۲ سال و ۶ ماه
    - کودک دوم: ۴ سال و ۱ روز

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

- `FlightTotalPayable`

  decimal

  required

  مبلغ کل مربوط به پرواز

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

- `HotelTotalPayable`

  decimal

  required

  مبلغ کل مربوط به هتل

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

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

<br>

## Sample Request

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

```json
{
    "Username": "testdev1",
    "Password": "25f9e794323b453885f5181f1b624d0b",
    "DepartureSegment": {
        "FlightNumber": "412",
        "FlightDate": "2025-12-17 18:00",
        "OriginIataCode": "THR",
        "DestinationIataCode": "KIH",
        "FareName": "THRMHD1"
    },
    "ReturningSegment": {
        "FlightNumber": "413",
        "FlightDate": "2025-12-20 10:00",
        "OriginIataCode": "KIH",
        "DestinationIataCode": "THR",
        "FareName": "MHD"
    },
    "CheckinDate": "2025-12-17",
    "CheckoutDate": "2025-12-20",
    "RoomList": [{
            "RoomTypeSepehrGlobalId": 5003,
            "BoardTypeCode": "BB",
            "AdultCount": 2,
            "ChildAgeList": []
        }
    ],
    "FlightTotalPayable": 17809900.00,
    "HotelTotalPayable": 18366500.00
}
```

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

```json
{
    "Username": "testdev1",
    "Password": "25f9e794323b453885f5181f1b624d0b",
    "DepartureSegment": {
        "FlightNumber": "789",
        "FlightDate": "2025-12-17 13:30",
        "OriginIataCode": "IKA",
        "DestinationIataCode": "IST",
        "FareName": "FF9"
    },
    "ReturningSegment": {
        "FlightNumber": "7845",
        "FlightDate": "2025-12-20 18:30",
        "OriginIataCode": "IST",
        "DestinationIataCode": "IKA",
        "FareName": "IKAISTTEST2"
    },
    "CheckinDate": "2025-12-17",
    "CheckoutDate": "2025-12-20",
    "RoomList": [{
            "RoomTypeSepehrGlobalId": 8235,
            "BoardTypeCode": "RO",
            "AdultCount": 2,
            "ChildAgeList": []
        }, {
            "RoomTypeSepehrGlobalId": 6468,
            "BoardTypeCode": "FF",
            "AdultCount": 1,
            "ChildAgeList": [3]
        }
    ],
    "FlightTotalPayable": 47200000.00,
    "HotelTotalPayable": 395750000.00
}
```

<br>

## Response Parameters

- `HotelLockId`

  number

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

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

- `DepartureFlightLockId`

  number

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

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

- `ReturningFlightLockId`

  number

  شناسه مربوط به قفل پرواز برگشت

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

- `ExpiryInMinute`

  number

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

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

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

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

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

<br>

## Sample Response

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

```json
{
    "HotelLockId": 10469,
    "DepartureFlightLockId": 270438,
    "ReturningFlightLockId": 270439,
    "ExpiryInMinute": 16
}
```

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

```json
{
    "HotelLockId": 10465,
    "DepartureFlightLockId": 270424,
    "ReturningFlightLockId": 270425,
    "ExpiryInMinute": 22
}
```

<br>

## Response common exceptions

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

| ExceptionType | توضیح خطا |
|---|---|
| `Error1004-NoEnoughCredit` | باقی مانده اعتبار حساب برای انجام این رزرو کافی نیست. |
| `Error1005-CreditDueDateReached` | مهلت پرداخت بدهی به اتمام رسیده است و انجام رزرو امکان پذیر نمی باشد |
| `Error1001-FlightNotFound` | پروازی با اطلاعات درخواستی پیدا نشد. |
| `Error1003-NoEnoughSeatAvailable` | تعداد صندلی درخواستی در پرواز موجود نمی باشد. |
| `Error1006-FareNotFound` | کلاس پروازی با اسم fare درخواستی پیدا نشد. این خطا معمولا زمانی اتفاق می افتد که نسبت به آخرین availability که دریافت کرده اید نرخ پرواز تغییر کرده باشد و شما هنوز تغییرات نرخی جدید را دریافت نکرده و با نرخ قبلی درخواست خود را ارسال کرده باشید. |
| `Error1011-FlightTimeMismatch` | ساعت پرواز درخواستی شما با ساعت پروازی سیستم مطابقت ندارد |
| `Error1013-FlightLockCountLimit` | زمانی که روی یک پرواز اقدام به قفل کردن بیش از 9 عدد صندلی نمایید، این خطا برگشت داده خواهد شد. |
| `Error1015-HotelLockCountLimit` | زمانی که روی یک نوع اتاق اقدام به قفل کردن بیش از 4 عدد اتاق نمایید، این خطا برگشت داده خواهد شد. |

<br>