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



## متد Book

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

<br>

API Endpoint

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

<br>

## 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 کشور ها [اینجا کلیک نمایید](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes).

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

      - `RoomList.AdultGuestList.Passport.PlaceOfIssueCountryCode`

        string

        required

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

        جهت مشاهده کد ISO کشور ها [اینجا کلیک نمایید](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes).

        به عنوان مثال برای ایران می توانید یکی از مقدارهای 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

  ملاحظات

<br>

## Sample Request

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

```json
{
  "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
}
```

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

```json
{
  "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
}
```

<br>

## Response Parameters

- `Pnr`

  string

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


:::danger
## نکات مهم

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

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

- وارد پنل سایت تامین کننده شده و با جستجو کردن کد ملی/شماره گذرنامه یا "YourLocalInventoryPnr" وضعیت رزرو را بررسی نمایید.
- با استفاده از وب سرویس و متد [RetrieveBooking/GetStatus](../../retrieve-booking/v1/get-status.md) وضعیت رزرو را بررسی نمایید.

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

<br>

## Sample Response

```json
{
  "Pnr": "V48T47"
}
```

<br>

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

<br>