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



## متد Book

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

<br>

API Endpoint

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

<br>

## Request Parameters

- `Username`

  string

  required

  نام کاربری

- `Password`

  string

  required

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

- `HotelLockId`

  number

  required

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

- `DepartureSegment`

  complex type

  required

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

  - `DepartureSegment.FlightNumber`

    string

    شماره پرواز

  - `DepartureSegment.DepartureDateTime`

    string

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

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

  - `DepartureSegment.OriginIataCode`

    string

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

  - `DepartureSegment.DestinationIataCode`

    string

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

  - `DepartureSegment.FareName`

    string

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

  - `DepartureSegment.LockId`

    number

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

- `ReturningSegment`

  complex type

  optional

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

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

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

- `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

      required

      تاریخ تولد میهمان با فرمت 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 می باشد

  - `RoomList.MobileNumber`

    string

    required

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

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

  - `RoomList.Email`

    string

    required

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

- `FlightTotalPayable`

  decimal

  required

  مبلغ کل پرواز

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

- `HotelTotalPayable`

  decimal

  required

  مبلغ کل هتل

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

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

- `YourLocalInventoryPnr`

  string

  optional

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

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

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

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

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

- `Remarks`

  string

  optional

  ملاحظات

<br>

## Sample Request

```json
{
    "Username": "testdev1",
    "Password": "25f9e794323b453885f5181f1b624d0b",
    "HotelLockId": 10469,
    "YourLocalInventoryPnr": "d102540b-22bb-4e1d-8fde-b4deea8585a6",
    "Email": "your-email-address@your-domain.com",
    "MobileNumber": "+989352283333",
    "Remarks": "",
    "DepartureSegment": {
        "FlightNumber": "412",
        "DepartureDateTime": "2025-12-17 18:00",
        "OriginIataCode": "THR",
        "DestinationIataCode": "KIH",
        "FareName": "THRMHD1",
        "LockId": 270438
    },
    "ReturningSegment": {
        "FlightNumber": "413",
        "DepartureDateTime": "2025-12-20 10:00",
        "OriginIataCode": "KIH",
        "DestinationIataCode": "THR",
        "FareName": "MHD",
        "LockId": 270439
    },
    "RoomList": [{
            "AdultGuestList": [{
                    "Title": "MR",
                    "FirstName": "BAHADOR",
                    "LastName": "MOOSAZADEH",
                    "BirthDate": "1995-12-16",
                    "IranianNationalId": "0011334983",
                    "Passport": null
                }, {
                    "Title": "MR",
                    "FirstName": "ZHINA",
                    "LastName": "ESMAEILIMATIN",
                    "BirthDate": "1995-12-16",
                    "IranianNationalId": "0011043164",
                    "Passport": null
                }
            ],
            "ChildGuestList": []
        }
    ],
    "FlightTotalPayable": 17809900.00,
    "HotelTotalPayable": 18366500.00
}
```

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

```json
{
    "Username": "testdev1",
    "Password": "25f9e794323b453885f5181f1b624d0b",
    "HotelLockId": 10465,
    "YourLocalInventoryPnr": "e71db5f2-b2f5-495d-81ef-49d90c9806b7",
    "Email": "your-email-address@your-domain.com",
    "MobileNumber": "+989352283333",
    "Remarks": "",
    "DepartureSegment": {
        "FlightNumber": "789",
        "DepartureDateTime": "2025-12-17 13:30",
        "OriginIataCode": "IKA",
        "DestinationIataCode": "IST",
        "FareName": "FF9",
        "LockId": 270424
    },
    "ReturningSegment": {
        "FlightNumber": "7845",
        "DepartureDateTime": "2025-12-20 18:30",
        "OriginIataCode": "IST",
        "DestinationIataCode": "IKA",
        "FareName": "IKAISTTEST2",
        "LockId": 270425
    },
    "RoomList": [{
            "AdultGuestList": [{
                    "Title": "MR",
                    "FirstName": "NAGHME",
                    "LastName": "YEGANEH ASL",
                    "BirthDate": "1995-12-15",
                    "IranianNationalId": null,
                    "Passport": {
                        "Number": "0010612408",
                        "ExpiryDate": "2027-12-15",
                        "NationalityCountryCode": "IR",
                        "PlaceOfIssueCountryCode": "IR"
                    }
                }, {
                    "Title": "MR",
                    "FirstName": "ZHINA",
                    "LastName": "BAHRAMIKIA",
                    "BirthDate": "1995-12-15",
                    "IranianNationalId": null,
                    "Passport": {
                        "Number": "0012015563",
                        "ExpiryDate": "2027-12-15",
                        "NationalityCountryCode": "IR",
                        "PlaceOfIssueCountryCode": "IR"
                    }
                }
            ],
            "ChildGuestList": []
        }, {
            "AdultGuestList": [{
                    "Title": "MR",
                    "FirstName": "BAHADOR",
                    "LastName": "POORESMAEILIFOOMANI",
                    "BirthDate": "1995-12-15",
                    "IranianNationalId": null,
                    "Passport": {
                        "Number": "0011557508",
                        "ExpiryDate": "2027-12-15",
                        "NationalityCountryCode": "IR",
                        "PlaceOfIssueCountryCode": "IR"
                    }
                }
            ],
            "ChildGuestList": [{
                    "Title": "MR",
                    "FirstName": "ROZA",
                    "LastName": "RAZIKHOSROSHAHI",
                    "BirthDate": "2022-12-19",
                    "IranianNationalId": null,
                    "Passport": {
                        "Number": "0010653295",
                        "ExpiryDate": "2027-12-15",
                        "NationalityCountryCode": "IR",
                        "PlaceOfIssueCountryCode": "IR"
                    }
                }
            ]
        }
    ],
    "FlightTotalPayable": 47200000.00,
    "HotelTotalPayable": 395750000.00
}
```

<br>

## Response Parameters

- `Pnr`

  string

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

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

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

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

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

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

<br>

## Sample Response

```json
{
    "Pnr": "DA4N4Y"
}
```

```json
{
    "Pnr": "K7S76U"
}
```

<br>

## Response common exceptions

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

| ExceptionType | توضیح خطا |
|---|---|
| `Error1001-FlightNotFound` | پروازی با اطلاعات درخواستی پیدا نشد. |
| `Error1003-NoEnoughSeatAvailable` | تعداد صندلی درخواستی در پرواز موجود نمی باشد. |
| `Error1004-NoEnoughCredit` | باقی مانده اعتبار حساب برای انجام این رزرو کافی نیست. |
| `Error1005-CreditDueDateReached` | مهلت پرداخت بدهی به اتمام رسیده است و انجام رزرو امکان پذیر نمی باشد |
| `Error1006-FareNotFound` | کلاس پروازی با اسم fare درخواستی پیدا نشد. |
| `Error1007-DuplicateClientPnr` | مقداری که به عنوان YourLocalInventoryPnr ارسال شده است تکراری بوده و قبلا در سیستم ثبت شده است. |
| `Error1010-LockReleased` | قفل رزرو آزاد شده است و رزرو قابل انجام شدن نیست. این اتفاق زمانی به وقوع می پیوندد که یا زمان بین قفل کردن تا فراخوانی متد Book، بیش از اندازه طولانی شده باشد و یا اینکه قفل رزرو توسط مدیر سیستم در سایت تامین کننده آزاد شده باشد. |
| `Error1011-FlightTimeMismatch` | ساعت پرواز درخواستی شما با ساعت پروازی سیستم مطابقت ندارد |
| `Error1012-ForbiddenNationality` | زمانی که پذیرش اتباع یک کشور خاص روی مسیری ممنوع باشد، این خطا برگشت داده خواهد شد. به عنوان مثال پذیرش اتباع محترم افغانستان و پاکستان در مسیر استانبول توسط هواپیمایی معراج ممنوع می باشد. |
| `Error1014-DuplicatePassengerName` | قبلا مسافری با کدملی یا شماره گذرنامه مشابه در پرواز رزرو شده است. |
| `Error1016-InvalidBirthdate` | تاریخ تولد مسافر غیر معتبر است. زمانی که تاریخ ارسال شده در بازه زمانی امروز تا 120 سال گذشته نباشد این خطا تولید می شود. |
| `Error1019-InfantAgeIsNotValid` | سن مسافر نوزاد هنگام پرواز در بازه بین 7 روز تا 2 سال نیست. اگر در رزرو دوطرفه با این خطا مواجه شدید بررسی نمایید که سن نوزاد هم در زمان پرواز رفت در بازه مجاز باشد و هم در زمان پرواز برگشت. درصورتی که نوزاد در پرواز رفت در بازه سنی مجاز باشد ولی هنگام پرواز برگشت سنش در بازه کودک قرار بگیرد، امکان انجام آن رزرو مقدور نخواهد بود. برای این منظور یا باید این مسافر را به عنوان کودک رزرو بگیرید یا اینکه برای رزرو با کارشناسان فروش تامین کننده مربوطه تماس حاصل بفرمایید. |
| `Error1020-ChildAgeIsNotValid` | سن مسافر کودک هنگام پرواز در بازه بین 2 تا 12 سال نیست. اگر در رزرو دوطرفه با این خطا مواجه شدید بررسی نمایید که سن کودک هم در زمان پرواز رفت در بازه مجاز باشد و هم در زمان پرواز برگشت. درصورتی که کودک در پرواز رفت در بازه سنی مجاز باشد ولی هنگام پرواز برگشت سنش در بازه بزرگسال قرار بگیرد، امکان انجام آن رزرو مقدور نخواهد بود. برای این منظور یا باید این مسافر را به عنوان بزرگسال رزرو بگیرید یا اینکه برای رزرو با کارشناسان فروش تامین کننده مربوطه تماس حاصل بفرمایید. |
| `Error1021-PriceMismatch` | نرخ درخواستی شما با نرخ سیستم مطابقت ندارد. |
| `Error1022-IpIsNotTrusted` | آی پی شما در سایت تامین کننده تراست نشده است. جهت تراست کردن آی پی با پشتیبانی سپهر تماس حاصل نمایید. |
| `Error1023-InvalidCredential` | نام کاربری یا رمز عبور اشتباه می باشد. |
| `Error1024-ForbiddenIp` | آی پی شما توسط تامین کننده مسدود شده است. جهت پیگیری موضوع با تامین کننده تماس بگیرید. |
| `Error1025-FlightIsClosed` | زمانی که یک پرواز وضعیت Ontime نداشته باشد (مثلا Close شده باشد) و شما اقدام به رزرو روی آن نمایید، این خطا را دریافت خواهید کرد. |
| `Error1028-HotelExtrabedExceeded` | تعداد تخت اضافه مورد نیاز برای انجام رزرو، بیش از گنجایش کلی تخت اضافه هتل می باشد. اگر دیتای availability را سمت خود cache می نمایید، برای کاهش احتمال بروز این خطا پیشنهاد می شود availability را در زمان های کوتاه تری دریافت نموده و cache خود را سریعتر بروز رسانی نمایید. |
| `Error1029-PassportExpiryDateMinimumLimit` | اعتبار تاریخ انقضای گذرنامه کمتر از حداقل مجاز آن می باشد. مثلا اگر در مسیری که حداقل اعتبار گذرنامه 6 ماهه لازم است، 5 ماه و 21 روز تا منقضی شدن گذرنامه مسافر باقی مانده باشد، سیستم این خطا را تولید خواهد کرد. در اکثر مسیرهای پروازی حداقل زمان باقی مانده معمولا 6 ماه می باشد، ولی این عدد با توجه به قوانین کشورهای مختلف ممکن است متفاوت باشد. همچنین مبنای محاسبه تاریخ، زمان پرواز می باشد و نه زمان رزرو. مثلا ممکن است مسافر در زمان رزرو 6 ماه اعتبار گذرنامه داشته باشد، ولی در روز پرواز، اعتبار گذرنامه آن کمتر از 6 ماه شده باشد که در این حالت سیستم خطا داده و اجازه رزرو نمی دهد. |
| `Error1030-PassportExpiryDateMaximumLimit` | تاریخ انقضای گذرنامه بیش از حد مجاز آن است. معمولا اکثر کشورها گذرنامه هایی با حداکثر تاریخ انقضای 10 ساله صادر می کنند. البته این عدد بر اساس هر کشور ممکن است متفاوت باشد. به عنوان مثال اگر برای کشوری که گذرنامه های حداکثر 10 ساله دارد، تاریخ انقضای گذرنامه بیش از 10 سال ارسال شود، سیستم این خطا را تولید خواهد کرد. |
| `Error1031-DuplicateDocumentNumberInSameRequest` | زمانی که در یک درخواست شما کد ملی یا شماره گذرنامه تکراری وجود داشته باشد، این خطا تولید می شود. برای جلوگیری از این خطا پیشنهاد می شود قبل از ارسال کردن درخواست رزرو، بررسی بفرمایید که در درخواست شما کد ملی یا شماره گذرنامه تکراری وجود نداشته باشد. |
| `Exception` | خطای نامشخص. جهت دریافت اطلاعات بیشتر باید به ErrorMessage داخل json برگشتی مراجعه نمود. |

<br>