مستندات وب سرویس

متد GetPenalty

Download Markdown for LLM

وب‌سرویس GetPenalty جهت محاسبه‌ی میزان جریمه ناشی از ویرایش اطلاعات مسافر مورد استفاده قرار می‌گیرد. در حال حاضر، امکان اعمال تغییرات زیر از طریق این وب‌سرویس فراهم است:

  • تغییر عنوان مسافر (آقا / خانم): در حال حاضر این نوع تغییر رایگان بوده و مشمول هزینه‌ نمی‌باشد.
  • تغییر نام مسافر (حداکثر یک یا دو کاراکتر): امکان‌پذیری این تغییر بسته به تنظیمات تأمین‌کننده خدمات است و مشمول هزینه می‌باشد. هدف اصلی استفاده از این متد، محاسبه هزینه جریمه تغییر نام مسافر است.
  • تغییر اطلاعات گذرنامه شامل شماره گذرنامه، تاریخ انقضا و محل صدور: در حال حاضر این نوع تغییر رایگان بوده و مشمول هزینه‌ نمی‌باشد.

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

در نهایت، پس از تأیید و در صورت تمایل، می‌توانید متد DoChange را برای اعمال نهایی تغییرات فراخوانی کنید.

توجه: سرویس «تغییر اطلاعات مسافر» ممکن است برای برخی از تأمین‌کنندگان غیرفعال باشد. در چنین شرایطی، هنگام فراخوانی متد GetPenalty، خطای Error1033-ChangePassengerInfoAccessDenied به عنوان پاسخ بازگردانده خواهد شد. در صورت دریافت این خطا، امکان تغییر اطلاعات مسافر از طریق وب‌سرویس وجود ندارد و لازم است تغییرات موردنظر به‌صورت مستقیم با تأمین‌کننده مربوطه انجام شود.


API Endpoint

POST https://{SupplierWebsiteUrl}/api/Partners/Flight/ChangePassengerInfo/V1/GetPenalty

Request Parameters

  • Username

    string

    required

    نام کاربری

  • Password

    string

    required

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

  • Pnr

    string

    required

    رفرنس رزروی که می خواهیم اطلاعات مسافران آن را تغییر دهیم.

  • PassengerList

    List(Passenger)

    required

    لیست مسافرانی که می خواهیم اطلاعات آنها را تغییر دهیم.

    + نمایش ویژگی‌های زیرمجموعه

    • PassengerList.Id

      string

      required

      این شناسه به‌صورت یکتا برای هر مسافر تعریف می‌شود و در خروجی متدهای زیر قابل دسترسی است:

    • PassengerList.PassengerNewData

      Complex type

      required

      اطلاعات جدیدی که می خواهید برای مسافر ثبت شود

      + نمایش ویژگی‌های زیرمجموعه

      • PassengerList.PassengerNewData.GenderType

        string

        required

        جنسیت مسافر که مقدار آن می‌تواند یکی از دو حالت زیر باشد:

        M : مرد

        F : زن

      • PassengerList.PassengerNewData.FirstName

        string

        required

        نام مسافر

      • PassengerList.PassengerNewData.LastName

        string

        required

        نام خانوادگی مسافر

      • PassengerList.PassengerNewData.Passport

        complex type

        optional/conditional

        اطلاعات گذرنامه مسافر

        در صورتی که مسافر با گذرنامه سفر می‌کند، لازم است اطلاعات گذرنامه وی در این فیلد ارسال شود

        + نمایش ویژگی‌های زیرمجموعه

        • PassengerList.PassengerNewData.Passport.Number

          string

          required

          شماره گذرنامه مسافر

        • PassengerList.PassengerNewData.Passport.ExpiryDate

          string

          required

          تاریخ انقضا گذرنامه با فرمت yyyy-MM-dd و به صورت میلادی.

        • PassengerList.PassengerNewData.Passport.PlaceOfIssueCountryCode

          string

          required

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

          جهت مشاهده کد ISO کشور ها اینجا کلیک نمایید.

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

  • Culture

    string

    required

    مشخص می‌کند پیام‌های خطا بر اساس کدام زبان خروجی داده شوند. مقدار این فیلد می‌تواند یکی از گزینه‌های en-US، ar-IQ یا fa-IR باشد.


Sample Request

نمونه درخواست تغییر عنوان و 2 کاراکتر یک مسافر در یک رزرو دو نفره

curl -X POST https://SepehrApiTest.ir/api/Partners/Flight/ChangePassengerInfo/V1/GetPenalty \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip, deflate" \
  -d '{
    "Username": "TestDev1",
    "Password": "25f9e794323b453885f5181f1b624d0b",
    "Pnr": "AG3B2V",
    "PassengerList": [{
            "Id": "ae3c2436-4be8-48b3-a3f1-1b2c2c03c32d",
            "PassengerNewData": {
                "GenderType": "M",
                "FirstName": "SEYEDEHKIANA",
                "LastName": "MOSTAMAND",
                "Passport": null
            }
        }, {
            "Id": "f0ecdce9-3734-4074-80ac-e3f0c173afd7",
            "PassengerNewData": {
                "GenderType": "F",
                "FirstName": "MOHADESEH",
                "LastName": "ASHRAFVAGHEFI",
                "Passport": null
            }
        }
    ],
    "Culture": "fa-IR"
}'

نمونه درخواست تغییر اطلاعات گذرنامه

curl -X POST https://SepehrApiTest.ir/api/Partners/Flight/ChangePassengerInfo/V1/GetPenalty \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip, deflate" \
  -d '{
    "Username": "TestDev1",
    "Password": "25f9e794323b453885f5181f1b624d0b",
    "Pnr": "I54848",
    "PassengerList": [{
            "Id": "355e2df8-fae0-4cad-86f4-5d511b9008bc",
            "PassengerNewData": {
                "GenderType": "M",
                "FirstName": "ABED",
                "LastName": "HOSSEYNI",
                "Passport": {
                    "Number": "A56753465",
                    "ExpiryDate": "2029-11-20",
                    "PlaceOfIssueCountryCode": "IR"
                }
            }
        }
    ],
    "Culture": "fa-IR"
}'

Response Parameters

  • PassengerList

    List(Passenger)

    لیستی از مسافران به همراه جزییات جریمه هر کدام.

    + نمایش ویژگی‌های زیرمجموعه

    • PassengerList.Id

      string

      شناسه منحصر به فرد مسافر

    • PassengerList.OldData

      complex type

      اطلاعات فعلی (ثبت‌شده) مسافر

      + نمایش ویژگی‌های زیرمجموعه

      • PassengerList.OldData.GenderType

        string

        جنسیت مسافر

      • PassengerList.OldData.FirstName

        string

        نام مسافر

      • PassengerList.OldData.LastName

        string

        نام خانوادگی مسافر

      • PassengerList.OldData.Passport

        string

        اطلاعات گذرنامه مسافر

        + نمایش ویژگی‌های زیرمجموعه

        • PassengerList.OldData.Passport.Number

          string

          شماره گذرنامه مسافر

        • PassengerList.OldData.Passport.ExpiryDate

          string

          تاریخ انقضا گذرنامه با فرمت yyyy-MM-dd و به صورت میلادی.

        • PassengerList.OldData.Passport.PlaceOfIssueCountryCode

          string

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

    • PassengerList.NewData

      complex type

      اطلاعات جدید که شما در request به این متد ارسال کرده اید

      ساختار NewData کاملا مشابه OldData می باشد.

    • PassengerList.Status

      boolean

      این فیلد نشان می‌دهد که آیا تغییرات مجاز هستند یا خیر. به عنوان مثال، اگر تعداد کاراکترهای تغییر یافته در نام مسافر (مثلاً ۳ کاراکتر) بیشتر از تعداد کاراکترهای مجاز برای تغییر (مثلاً ۲ کاراکتر) باشد، مقدار این فیلد false خواهد بود.

    • PassengerList.ErrorMessage

      string

      اگر مقدار فیلد Status برابر با false باشد، این فیلد حاوی توضیحاتی است که دلیل عدم امکان اعمال تغییرات را مشخص می‌کند.

    • PassengerList.Penalty

      decimal

      این مبلغ نشان‌دهنده هزینه‌ای است که بابت تغییرات انجام‌شده از حساب کاربری شما کسر می‌شود.


Sample Response

نمونه پاسخ تغییر عنوان و 2 کاراکتر یک مسافر در یک رزرو دو نفره

{
    "PassengerList": [{
            "Id": "ae3c2436-4be8-48b3-a3f1-1b2c2c03c32d",
            "OldData": {
                "GenderType": "M",
                "FirstName": "SEYEDEHKIANA",
                "LastName": "MOSTAMAND",
                "Passport": null
            },
            "NewData": {
                "GenderType": "M",
                "FirstName": "SEYEDEHKIANA",
                "LastName": "MOSTAMAND",
                "Passport": null
            },
            "Status": true,
            "ErrorMessage": "",
            "Penalty": 0.0
        }, {
            "Id": "f0ecdce9-3734-4074-80ac-e3f0c173afd7",
            "OldData": {
                "GenderType": "M",
                "FirstName": "MOHADES",
                "LastName": "ASHRAFVAGHEFI",
                "Passport": null
            },
            "NewData": {
                "GenderType": "F",
                "FirstName": "MOHADESEH",
                "LastName": "ASHRAFVAGHEFI",
                "Passport": null
            },
            "Status": true,
            "ErrorMessage": "",
            "Penalty": 2000000.0
        }
    ]
}

نمونه پاسخ تغییر اطلاعات گذرنامه

{
    "PassengerList": [{
            "Id": "355e2df8-fae0-4cad-86f4-5d511b9008bc",
            "OldData": {
                "GenderType": "M",
                "FirstName": "ABED",
                "LastName": "HOSSEYNI",
                "Passport": {
                    "Number": "A15793202",
                    "ExpiryDate": "2028-01-28",
                    "PlaceOfIssueCountryCode": "IR"
                }
            },
            "NewData": {
                "GenderType": "M",
                "FirstName": "ABED",
                "LastName": "HOSSEYNI",
                "Passport": {
                    "Number": "A56753465",
                    "ExpiryDate": "2029-11-20",
                    "PlaceOfIssueCountryCode": "IR"
                }
            },
            "Status": true,
            "ErrorMessage": "",
            "Penalty": 0.0
        }
    ]
}

Response common exceptions

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

ExceptionType توضیح خطا
Error1032-ReservationChangePassengerInfoIsDoneOnceBefore این رزرو قبلا اصلاح شده است و امکان ویرایش مجدد آن وجود ندارد.
Error1033-ChangePassengerInfoAccessDenied سرویس ویرایش اطلاعات مسافران روی سیستم تامین کننده فعال نیست.
Exception خطای نامشخص. جهت دریافت اطلاعات بیشتر باید به ErrorMessage داخل json برگشتی مراجعه نمود.