booking

Download Markdown for LLM

متد Book

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

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


API Endpoint

POST https://{SupplierWebsiteUrl}/api/Partners/Flight/Booking/V12/Book

Request Parameters


Sample Request

Sample Request - پرواز داخلی - یکطرفه - یک بزرگسال - یک کودک - یک نوزاد

curl -X POST https://SepehrApiTest.ir/api/Partners/Flight/Booking/V12/Book \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip, deflate" \
  -d '{
  "UserName": "testdev1",
  "Password": "25f9e794323b453885f5181f1b624d0b",
  "DepartureSegment": {
    "FlightNumber": "2201",
    "DepartureDateTime": "2024-04-14 11:00",
    "OriginIataCode": "AWZ",
    "DestinationIataCode": "IFN",
    "FareName": "AB13",
    "LockId": null
  },
  "ReturningSegment": null,
  "AdultPassengerList": [
    {
      "Title": "MR",
      "FirstName": "PARNIA",
      "LastName": "BARANRIZ",
      "BirthDate": "1994-04-13",
      "IranianNationalId": "0012281387",
      "IraqiNationalId": null,
      "Passport": null
    }
  ],
  "ChildPassengerList": [
    {
      "Title": "MR",
      "FirstName": "KHALED",
      "LastName": "FARAHANI",
      "BirthDate": "2016-04-13",
      "IranianNationalId": "0011779845",
      "IraqiNationalId": null,
      "Passport": null
    }
  ],
  "InfantPassengerList": [
    {
      "Title": "MR",
      "FirstName": "HADISEH",
      "LastName": "FAKHMI",
      "BirthDate": "2023-04-13",
      "IranianNationalId": "0011600101",
      "IraqiNationalId": null,
      "Passport": null
    }
  ],
  "MobileNumber": "+989352283333",
  "Email": "your-email-address@your-domain.com",
  "TotalPayable": 7400000,
  "YourLocalInventoryPnr": "8daccada-f56c-4663-9f87-ce38c130ec06",
  "Remarks": null
}'

Sample Request - پرواز خارجی - یکطرفه - یک بزرگسال - یک کودک - یک نوزاد

curl -X POST https://SepehrApiTest.ir/api/Partners/Flight/Booking/V12/Book \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip, deflate" \
  -d '{
  "UserName": "testdev1",
  "Password": "25f9e794323b453885f5181f1b624d0b",
  "DepartureSegment": {
    "FlightNumber": "1111",
    "DepartureDateTime": "2024-04-14 10:30",
    "OriginIataCode": "IKA",
    "DestinationIataCode": "IST",
    "FareName": "Y IKANJF13",
    "LockId": null
  },
  "ReturningSegment": null,
  "AdultPassengerList": [
    {
      "Title": "MR",
      "FirstName": "SAYEDMOHAMMAD",
      "LastName": "SEDIGHI DEHKORDI",
      "BirthDate": "1994-04-13",
      "IranianNationalId": null,
      "IraqiNationalId": null,
      "Passport": {
        "Number": "A41497039",
        "ExpiryDate": "2026-04-13",
        "NationalityCountryCode": "IR",
        "PlaceOfIssueCountryCode": "IR"
      }
    }
  ],
  "ChildPassengerList": [
    {
      "Title": "MR",
      "FirstName": "NAGHME",
      "LastName": "FORSATI",
      "BirthDate": "2016-04-13",
      "IranianNationalId": null,
      "IraqiNationalId": null,
      "Passport": {
        "Number": "A16068656",
        "ExpiryDate": "2026-04-13",
        "NationalityCountryCode": "IR",
        "PlaceOfIssueCountryCode": "IR"
      }
    }
  ],
  "InfantPassengerList": [
    {
      "Title": "MR",
      "FirstName": "MAHSHAD",
      "LastName": "ALINEZHAD",
      "BirthDate": "2023-04-13",
      "IranianNationalId": null,
      "IraqiNationalId": null,
      "Passport": {
        "Number": "F46128168",
        "ExpiryDate": "2026-04-13",
        "NationalityCountryCode": "IR",
        "PlaceOfIssueCountryCode": "IR"
      }
    }
  ],
  "MobileNumber": "+989352283333",
  "Email": "your-email-address@your-domain.com",
  "TotalPayable": 15500000,
  "YourLocalInventoryPnr": "cace22fb-c124-4629-b7da-2a3c2cbe97e4",
  "Remarks": null
}'

Response Parameters


Sample Response

Sample Response - پرواز داخلی - یکطرفه - یک بزرگسال - یک کودک - یک نوزاد

{
    "LocalPnr": "L3M4YX",
    "PassengerList": [{
            "Id": "49ff2721-f598-4f0f-8d1a-dec1227d5520",
            "FirstName": "PARNIA",
            "LastName": "BARANRIZ",
            "NationalityCountryCode": "IR",
            "IranianNationalId": "0012281387",
            "Passport": null,
            "DepartureSegment": {
                "OriginalPnr": "L3M4YX",
                "LocalTicketNumber": "1412641",
                "OriginalTicketNumber": "1412641",
                "OriginalSupplierName": "",
                "FlightNumber": "2201",
                "FlightDate": "2024-04-14 11:00",
                "OriginIataCode": "AWZ",
                "DestinationIataCode": "IFN",
                "PriceBreakdown": {
                    "BaseFare": 3450000,
                    "Tax": 0,
                    "TotalFare": 3450000,
                    "CommissionPercent": 0,
                    "CalculatedAmountOfCommissionPercent": 0,
                    "CommissionValue": 0,
                    "Payable": 3450000
                }
            },
            "ReturningSegment": null
        }, {
            "Id": "233a363a-4b1f-4957-8f67-178566a79a51",
            "FirstName": "KHALED",
            "LastName": "FARAHANI",
            "NationalityCountryCode": "IR",
            "IranianNationalId": "0011779845",
            "IraqiNationalId": null,
            "Passport": null,
            "DepartureSegment": {
                "OriginalPnr": "L3M4YX",
                "LocalTicketNumber": "1412642",
                "OriginalTicketNumber": "1412642",
                "OriginalSupplierName": "",
                "FlightNumber": "2201",
                "FlightDate": "2024-04-14 11:00",
                "OriginIataCode": "AWZ",
                "DestinationIataCode": "IFN",
                "PriceBreakdown": {
                    "BaseFare": 3450000,
                    "Tax": 0,
                    "TotalFare": 3450000,
                    "CommissionPercent": 0,
                    "CalculatedAmountOfCommissionPercent": 0,
                    "CommissionValue": 0,
                    "Payable": 3450000
                }
            },
            "ReturningSegment": null
        }, {
            "Id": "3ad26250-93eb-4574-be25-8c65d2d33bf3",
            "FirstName": "HADISEH",
            "LastName": "FAKHMI",
            "NationalityCountryCode": "IR",
            "IranianNationalId": "0011600101",
            "IraqiNationalId": null,
            "Passport": null,
            "DepartureSegment": {
                "OriginalPnr": "L3M4YX",
                "LocalTicketNumber": "1412643",
                "OriginalTicketNumber": "1412643",
                "OriginalSupplierName": "",
                "FlightNumber": "2201",
                "FlightDate": "2024-04-14 11:00",
                "OriginIataCode": "AWZ",
                "DestinationIataCode": "IFN",
                "PriceBreakdown": {
                    "BaseFare": 500000,
                    "Tax": 0,
                    "TotalFare": 500000,
                    "CommissionPercent": 0,
                    "CalculatedAmountOfCommissionPercent": 0,
                    "CommissionValue": 0,
                    "Payable": 500000
                }
            },
            "ReturningSegment": null
        }
    ]
}

Sample Response - پرواز خارجی - یکطرفه - یک بزرگسال - یک کودک - یک نوزاد

{
    "LocalPnr": "PUSI72",
    "PassengerList": [{
            "Id": "17ff49e0-c07f-4bc8-969d-faf0541d75f0",
            "FirstName": "SAYEDMOHAMMAD",
            "LastName": "SEDIGHI DEHKORDI",
            "NationalityCountryCode": "IR",
            "IranianNationalId": null,
            "IraqiNationalId": null,
            "Passport": {
                "Number": "A41497039",
                "ExpiryDate": "2026-04-13",
                "PlaceOfIssueCountryCode": "IR"
            },
            "DepartureSegment": {
                "OriginalPnr": "PUSI72",
                "LocalTicketNumber": "1412644",
                "OriginalTicketNumber": "1412644",
                "OriginalSupplierName": "",
                "FlightNumber": "1111",
                "FlightDate": "2024-04-14 10:30",
                "OriginIataCode": "IKA",
                "DestinationIataCode": "IST",
                "PriceBreakdown": {
                    "BaseFare": 8500000,
                    "Tax": 0,
                    "TotalFare": 8500000,
                    "CommissionPercent": 0,
                    "CalculatedAmountOfCommissionPercent": 0,
                    "CommissionValue": 0,
                    "Payable": 8500000
                }
            },
            "ReturningSegment": null
        }, {
            "Id": "8a08f91b-2a41-4dd4-9226-22efe1347157",
            "FirstName": "NAGHME",
            "LastName": "FORSATI",
            "NationalityCountryCode": "IR",
            "IranianNationalId": null,
            "IraqiNationalId": null,
            "Passport": {
                "Number": "A16068656",
                "ExpiryDate": "2026-04-13",
                "PlaceOfIssueCountryCode": "IR"
            },
            "DepartureSegment": {
                "OriginalPnr": "PUSI72",
                "LocalTicketNumber": "1412645",
                "OriginalTicketNumber": "1412645",
                "OriginalSupplierName": "",
                "FlightNumber": "1111",
                "FlightDate": "2024-04-14 10:30",
                "OriginIataCode": "IKA",
                "DestinationIataCode": "IST",
                "PriceBreakdown": {
                    "BaseFare": 6000000,
                    "Tax": 0,
                    "TotalFare": 6000000,
                    "CommissionPercent": 0,
                    "CalculatedAmountOfCommissionPercent": 0,
                    "CommissionValue": 0,
                    "Payable": 6000000
                }
            },
            "ReturningSegment": null
        }, {
            "Id": "612a0794-f63f-4512-acb1-bf5c39ae0005",
            "FirstName": "MAHSHAD",
            "LastName": "ALINEZHAD",
            "NationalityCountryCode": "IR",
            "IranianNationalId": null,
            "IraqiNationalId": null,
            "Passport": {
                "Number": "F46128168",
                "ExpiryDate": "2026-04-13",
                "PlaceOfIssueCountryCode": "IR"
            },
            "DepartureSegment": {
                "OriginalPnr": "PUSI72",
                "LocalTicketNumber": "1412646",
                "OriginalTicketNumber": "1412646",
                "OriginalSupplierName": "",
                "FlightNumber": "1111",
                "FlightDate": "2024-04-14 10:30",
                "OriginIataCode": "IKA",
                "DestinationIataCode": "IST",
                "PriceBreakdown": {
                    "BaseFare": 1000000,
                    "Tax": 0,
                    "TotalFare": 1000000,
                    "CommissionPercent": 0,
                    "CalculatedAmountOfCommissionPercent": 0,
                    "CommissionValue": 0,
                    "Payable": 1000000
                }
            },
            "ReturningSegment": null
        }
    ]
}

نکات مهم

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

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

  • وارد پنل سایت تامین کننده شده و با جستجو کردن کد ملی/شماره گذرنامه یا "YourLocalInventoryPnr" وضعیت رزرو را بررسی نمایید.
  • با استفاده از وب سرویس و متد RetrieveBooking/GetStatus وضعیت رزرو را بررسی نمایید.

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


Response common exceptions

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

ExceptionType توضیح خطا
Error1001-FlightNotFound پروازی با اطلاعات درخواستی پیدا نشد.
Error1003-NoEnoughSeatAvailable تعداد صندلی درخواستی در پرواز موجود نمی باشد.
Error1004-NoEnoughCredit باقی مانده اعتبار حساب برای انجام این رزرو کافی نیست.
Error1005-CreditDueDateReached مهلت پرداخت بدهی به اتمام رسیده است و انجام رزرو امکان پذیر نمی باشد
Error1006-FareNotFound کلاس پروازی با اسم fare درخواستی پیدا نشد. این خطا معمولا زمانی اتفاق می افتد که نسبت به آخرین availability که دریافت کرده اید نرخ پرواز تغییر کرده باشد و شما هنوز تغییرات نرخی جدید را دریافت نکرده و با نرخ قبلی درخواست خود را ارسال کرده باشید.
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 نرخ درخواستی شما با نرخ سیستم مطابقت ندارد. این خطا معمولا زمانی اتفاق می افتد که کمیسیون داده شده به کاربر شما توسط تامین کننده تغییر کرده باشد و شما آخرین تغییرات در بخش availability دریافت نکرده باشید و همچنان با نرخ قبلی درخواست خود را ارسال نمایید.
Error1022-IpIsNotTrusted آی پی شما در سایت تامین کننده تراست نشده است. جهت تراست کردن آی پی با پشتیبانی سپهر تماس حاصل نمایید.
Error1023-InvalidCredential نام کاربری یا رمز عبور اشتباه می باشد.
Error1024-ForbiddenIp آی پی شما توسط تامین کننده مسدود شده است. جهت پیگیری موضوع با تامین کننده تماس بگیرید.
Error1025-FlightIsClosed زمانی که یک پرواز وضعیت Ontime نداشته باشد (مثلا Close شده باشد) و شما اقدام به رزرو روی آن نمایید، این خطا را دریافت خواهید کرد.
Error1029-PassportExpiryDateMinimumLimit اعتبار تاریخ انقضای گذرنامه کمتر از حداقل مجاز آن می باشد. مثلا اگر در مسیری که حداقل اعتبار گذرنامه 6 ماهه لازم است، 5 ماه و 21 روز تا منقضی شدن گذرنامه مسافر باقی مانده باشد، سیستم این خطا را تولید خواهد کرد. در اکثر مسیرهای پروازی حداقل زمان باقی مانده معمولا 6 ماه می باشد، ولی این عدد با توجه به قوانین کشورهای مختلف ممکن است متفاوت باشد. همچنین مبنای محاسبه تاریخ، زمان پرواز می باشد و نه زمان رزرو. مثلا ممکن است مسافر در زمان رزرو 6 ماه اعتبار گذرنامه داشته باشد، ولی در روز پرواز، اعتبار گذرنامه آن کمتر از 6 ماه شده باشد که در این حالت سیستم خطا داده و اجازه رزرو نمی دهد.
Error1030-PassportExpiryDateMaximumLimit تاریخ انقضای گذرنامه بیش از حد مجاز آن است. معمولا اکثر کشورها گذرنامه هایی با حداکثر تاریخ انقضای 10 سال صادر می کنند. البته این عدد بر اساس هر کشور ممکن است متفاوت باشد. به عنوان مثال اگر برای کشوری که گذرنامه های حداکثر 10 ساله دارد، تاریخ انقضای گذرنامه بیش از 10 سال ارسال شود، سیستم این خطا را تولید خواهد کرد.
Error1031-DuplicateDocumentNumberInSameRequest زمانی که در یک درخواست شما کد ملی یا شماره گذرنامه تکراری وجود داشته باشد، این خطا تولید می شود. برای جلوگیری از این خطا پیشنهاد می شود قبل از ارسال کردن درخواست رزرو، بررسی بفرمایید که در درخواست شما کد ملی یا شماره گذرنامه تکراری وجود نداشته باشد.
Exception خطای نامشخص. جهت دریافت اطلاعات بیشتر باید به ErrorMessage داخل json برگشتی مراجعه نمود.