GetList | Changed Schedule Passengers | پرواز | مستندات وب سرویس سپهر

متد GetList

این متد لیست رزروهایی که تغییری در برنامه پروازی مسافران آنها داده شده است را بر می گرداند.

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

نکته مهم در خصوص ثبت تغییرات توسط تأمین‌کننده

اطلاعات این وب‌سرویس صرفاً بر اساس تغییراتی ارائه می‌شود که توسط تأمین‌کننده پرواز در سیستم ثبت و به ماژول تغییر برنامه پروازی سپهر اعلام شده باشد.

ممکن است تأمین‌کننده ساعت پرواز را تغییر دهد، پروازی را لغو کند یا تغییر دیگری در برنامه پروازی ایجاد نماید، اما این تغییر را در سیستم خود ثبت نکرده یا آن را به ماژول تغییر برنامه پروازی سپهر اعلام نکرده باشد. در چنین شرایطی، طبیعتاً اطلاعات مربوط به آن تغییر در این وب‌سرویس نیز ارائه نخواهد شد.

مسئولیت ثبت و اعلام صحیح و به‌موقع تغییرات برنامه پروازی بر عهده تأمین‌کننده پرواز است و سپهر صرفاً تغییراتی را که از سوی تأمین‌کننده دریافت و در سیستم ثبت شده‌اند، در این وب‌سرویس ارائه می‌کند.

بنابراین، در صورتی که کلاینت متوجه شود تغییر ایجادشده در برنامه پروازی توسط تأمین‌کننده در سیستم ثبت نشده است، لازم است موضوع را مستقیماً به تأمین‌کننده اعلام کرده و از وی درخواست کند تغییر مربوطه را در سیستم ثبت و اعلام نماید. تا زمانی که این تغییر توسط تأمین‌کننده ثبت و به سپهر اعلام نشده باشد، امکان ارائه آن در خروجی این وب‌سرویس وجود نخواهد داشت.

در نتیجه، عدم مشاهده یک تغییر در خروجی این وب‌سرویس لزوماً به معنی عدم وقوع آن تغییر در سیستم تأمین‌کننده نیست.

نحوه مدیریت محدودیت تعداد خروجی (صفحه‌بندی) سقف تعداد رکوردهای برگشتی در هر بار فراخوانی این وب‌سرویس ۵۰۰ رکورد است. اگر حجم تغییرات بیش از این تعداد باشد، باید با ذخیره کردن بزرگ‌ترین تاریخ ChangeScheduleDateTimeUtc و قرار دادن آن در فیلد FromDateTimeUtc درخواست بعدی، مجدداً متد را فراخوانی کنید تا رکوردهای بعدی برای شما ارسال شود.

نمایش پیام به مسافر سیستم به طور خودکار مناسب‌ترین متن اطلاع‌رسانی را در فیلد Message تولید و ارسال می‌کند. هرچند امکان تولید پیام شخصی‌سازی‌شده بر اساس فیلدهای تفکیک‌شده وجود دارد، اما با توجه به لاجیک بسیار پیچیده و زمان‌بر بودن پیاده‌سازی آن، پیشنهاد می‌کنیم پیام‌ها را مستقیماً از روی فیلد Message برای مسافران ارسال کنید.

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

رویکرد اشتباه: استفاده از پیام مسافر اول برای کل اعضای رزرو.

رویکرد درست: در پردازش داده‌ها، مسافرانِ هر رزرو را بر اساس محتوای فیلد Message دسته‌بندی (Group) کنید. سپس برای مسافرانی که متن پیام کاملاً مشابهی دارند، یک پیامک مشترک ارسال کنید تا هم در هزینه‌های ارسال پیامک صرفه‌جویی شود و هم اطلاعات نادرست به سایر مسافران ارسال نگردد.

نکته مهم در مورد استرداد اگر وضعیت پرواز مسافر Cancelled شد، این به معنی کنسل شدن خودِ رزرو نیست. برای اینکه رزرو واقعا کنسل شود و مبلغ به اعتبار شما برگردد، باید حتما متد DoRefund را فراخوانی کنید. تا قبل از اجرای DoRefund، هیچ مبلغی به اعتبار شما باز نمی‌گردد و نباید وجهی به مسافر استرداد شود؛ چون ممکن است وضعیت پرواز بعدا از Cancelled به Reinstated تغییر کند و رزرو دوباره معتبر شود.

همچنین اگر DoRefund را اجرا کرده باشید، حتی در صورت برقراری مجدد پرواز، رزرو دیگر به حالت Reinstated برنمی‌گردد.

نکته مهم دیگر این است که ممکن است مسافری که در رکورد فعلی با وضعیت Cancelled نمایش داده می‌شود، در رکوردهای بعدی Reinstated شده باشد. بنابراین قبل از فراخوانی DoRefund، حتما متد GetPenalty را بررسی کنید تا مطمئن شوید وضعیت مسافر همچنان Cancelled و استرداد بدون جریمه همچنان مجاز است.

API Endpoint

POST https://{SupplierWebsiteUrl}/api/Partners/ChangedSchedulePassengers/V2/GetList

Request Parameters

Username

string

required

نام کاربری
Password

string

required

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

datetime

required

تاریخ و زمان مبدأ جهت دریافت تغییرات جدید (به وقت UTC و با فرمت yyyy-MM-dd HH:mm:ss).

در اولین درخواست، تاریخ مبدأ مورد نظر خود را ارسال کنید. در پاسخ، فهرستی از Bookingها برمی‌گردد که هرکدام دارای فیلد ChangeScheduleDateTimeUtc هستند. برای فراخوانی‌های بعدی، باید بزرگ‌ترین (جدیدترین) زمانِ دریافت شده در این فیلد را سمت خود ذخیره کرده و آن را در فیلد FromDateTimeUtc درخواست بعدی بفرستید تا فقط تغییرات جدیدتر از آن زمان برای شما ارسال شود.

Sample Request

curl -X POST https://SepehrApiTest.ir/api/Partners/ChangedSchedulePassengers/V2/GetList \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip, deflate" \
  -d '{
  "Username": "testdev1",
  "Password": "25f9e794323b453885f5181f1b624d0b",
  "FromDateTimeUtc": "2024-02-01 00:00:00"
}'

Response Parameters

BookingList

List(Booking)

لیست رزروهای که پرواز مسافران آن تغییر برنامه داده شده است

+ نمایش ویژگی‌های زیرمجموعه
- BookingList.RecordId
  
  integer
  
  شناسه یکتای مربوط به رکورد تغییرات.
  
  شما می‌توانید از این فیلد برای اعتبارسنجی یکتایی داده‌ها در سمت خود استفاده کنید تا از ثبت و پردازش مجدد داده‌های تکراری جلوگیری شود.
- BookingList.Pnr
  
  string
  
  رفرنس رزرو
- BookingList.BookingDateTimeUtc
  
  string
  
  زمان انجام شدن رزرو
  
  فرمت این فیلد yyyy-MM-dd HH:mm:ss می باشد
  
  تاریخ میلادی و به ناحیه زمانی UTC می باشد
- BookingList.ChangeScheduleDateTimeUtc
  
  string
  
  زمان انجام شدن تغییرات
  
  فرمت این فیلد yyyy-MM-dd HH:mm:ss می باشد
  
  تاریخ میلادی و به ناحیه زمانی UTC می باشد
- BookingList.YourLocalInventoryPnr
  
  string
  
  رفرنس سیستم داخلی شما
- BookingList.IsReserveIssued
  
  boolean
  
  این فیلد مشخص می‌کند که رزرو مسافر نهایی و صادر شده است یا همچنان در وضعیت موقت قرار دارد و هنوز صادر نشده است.
  
  از آنجا که در این وب‌سرویس، برای هر دو نوع رزروِ موقت (صادرنشده) و رزروِ نهایی‌شده، در صورت تغییر برنامه پروازی رکورد خروجی برگردانده می‌شود، این فیلد در پاسخ قرار داده شده است تا بتوانید وضعیت رزرو را تشخیص دهید.
  
  در صورتی که بخواهید بر اساس موقت یا نهایی بودن رزرو، متن یا نحوه اطلاع‌رسانی متفاوتی به مسافر ارسال کنید، می‌توانید از مقدار این فیلد استفاده کنید.
- BookingList.PassengerList
  
  List(Passenger)
  
  لیست مسافران
  
  + نمایش ویژگی‌های زیرمجموعه
  - BookingList.PassengerList.AgeType
    
    string
    
    گروه سنی مسافر که شامل یکی از مقادیر ADL یا CHD یا INF می باشد
  - BookingList.PassengerList.FirstName
    
    string
    
    نام مسافر
  - BookingList.PassengerList.LastName
    
    string
    
    نام خانوادگی مسافر
  - BookingList.PassengerList.Gender
    
    string
    
    جنسیت مسافر که یکی از مقادیر M یا F را دارد.
  - BookingList.PassengerList.TicketNumber
    
    string
    
    شماره بلیط
  - BookingList.PassengerList.CabinType
    
    string
    
    نوع کابین
  - BookingList.PassengerList.Status
    
    string
    
    مشخص‌کننده وضعیت و جنس تغییرات اعمال‌شده بر روی رزرو مسافر. این فیلد شامل یکی از مقادیر زیر است:
    
    Cancelled
    
    پرواز باطل شده یا به علت کاهش لود (کاهش ظرفیت مجاز پرواز)، مسافر از لیست پرواز حذف شده و امکان سفر ندارد.
    
    FlightTimeChanged
    
    زمان پرواز تغییر کرده است (شامل تعجیل یا تأخیر در ساعت پرواز).
    
    Reinstated
    
    پروازِ ابطال‌شده قبلی، مجدداً احیا و برقرار شده است و رزرو مسافر به حالت معتبر بازمی‌گردد.
  - BookingList.PassengerList.Cancelled
    
    complex type
    
    این فیلد جزئیات و اطلاعات تکمیلی مربوط به ابطال پرواز را ارائه می‌دهد.
    
    این فیلد تنها زمانی مقداردهی می‌شود که مقدار فیلد Status برابر با Cancelled باشد؛ در غیر این صورت، این فیلد به صورت null فرستاده می‌شود.
    
    + نمایش ویژگی‌های زیرمجموعه
    
    BookingList.PassengerList.Cancelled.CancellationReason
    
    string
    
    بیان‌کننده دلیل ابطال پرواز یا کاهش لود مسافر. این فیلد یکی از مقادیر زیر را شامل می‌شود:
    
    FlightCancellation
    
    ابطال کامل پرواز.
    
    ReducedFlightCapacityDueToAircraftChange
    
    کاهش ظرفیت پرواز به دلیل تغییر تایپ هواپیما به هواپیمای کوچک‌تر.
    
    ReducedFlightCapacityDueToTemperature
    
    کاهش ظرفیت پرواز به دلیل محدودیت‌های دمای هوا (محدودیت وزن برخاست).
    
    ReducedFlightCapacityDueToPublicHealthEmergency
    
    کاهش ظرفیت پرواز به علت شرایط اضطراری سلامت و بهداشت عمومی.
    
    ReducedFlightCapacityDueToOverbooking
    
    کاهش ظرفیت به دلیل اوربوکینگ (فروش بیش از ظرفیت پرواز).
    
    BookingList.PassengerList.Cancelled.PassengerResponseDeadlineUtc
    
    datetime
    
    ضرب‌الاجل و آخرین مهلت پاسخگویی مسافر برای تعیین تکلیف پرواز جایگزین (به وقت UTC).
    
    چنانچه برای پرواز ابطال‌شده، پروازهای جایگزینی در لیست AlternativeFlightList ارائه شده باشد، مهلت زمانی پاسخ مسافر (تایید یا رد پیشنهادات) در این فیلد مشخص می‌گردد. در صورتی که هیچ پرواز جایگزینی پیشنهاد نشده باشد، مقدار این فیلد برابر با null ارسال می‌شود.
  - BookingList.PassengerList.FlightTimeChanged
    
    complex type
    
    این فیلد اطلاعات تکمیلی و جزئیات مربوط به تغییر ساعت پرواز (تعجیل یا تاخیر) را ارائه می‌دهد.
    
    این فیلد تنها زمانی مقداردهی می‌شود که مقدار فیلد Status برابر با FlightTimeChanged باشد؛ در غیر این صورت، مقدار آن به صورت null ارسال خواهد شد.
    
    + نمایش ویژگی‌های زیرمجموعه
    
    BookingList.PassengerList.FlightTimeChanged.PreviousFlightTime
    
    datetime
    
    این فیلد زمان اولیه پرواز (پیش از تغییر ساعت) را ارائه می‌دهد.
    
    اطلاعات زمانی داخلی این فیلد با فرمت yyyy-MM-dd HH:mm و بر اساس ناحیه زمانی فرودگاه مبدا پرواز می باشد
    
    BookingList.PassengerList.FlightTimeChanged.CurrentFlightTime
    
    datetime
    
    مشخص‌کننده ساعت جدید پرواز (پس از اعمال تاخیر یا تعجیل).
    
    اطلاعات زمانی داخلی این فیلد با فرمت yyyy-MM-dd HH:mm و بر اساس ناحیه زمانی فرودگاه مبدا پرواز می باشد
    
    BookingList.PassengerList.FlightTimeChanged.IsRefundWithoutPenaltyAllowed
    
    boolean
    
    مشخص‌کننده مجاز بودن استرداد بدون جریمه بلیط.
    
    اگر مقدار این فیلد true باشد، مسافر حق دارد به علت تغییرات زمانی پرواز، کل مبلغ بلیط را بدون کسر هرگونه جریمه استرداد نماید. در صورتی که مقدار این فیلد false باشد، کنسلی رزرو تابع قوانین عادی ریفاند بوده و جریمه استرداد از آن کسر خواهد شد.
    
    BookingList.PassengerList.FlightTimeChanged.PassengerResponseDeadlineUtc
    
    datetime
    
    ضرب‌الاجل و آخرین مهلت پاسخگویی مسافر/آژانس (به وقت UTC) جهت تعیین تکلیف رزرو (تأیید پرواز جایگزین یا نهایی کردن استرداد بدون جریمه).
    
    این فیلد زمانی مقداردهی می‌شود که پروازهای پیشنهادی جدیدی در لیست AlternativeFlightList ارائه شده باشد یا تغییر ساعت پرواز به گونه‌ای باشد که مسافر واجد شرایط استرداد بدون جریمه گردد (IsRefundWithoutPenaltyAllowed = true). در صورت عدم وجود هر دو حالت (یعنی عدم ارائه پرواز جایگزین و عدم امکان استرداد بدون جریمه)، این فیلد به صورت null فرستاده می‌شود.
  - BookingList.PassengerList.Reinstated
    
    complex type
    
    این فیلد اطلاعات مربوط به پروازی را ارائه می‌دهد که پیش‌تر با وضعیت ابطال اعلام شده بود و اکنون مجدداً برقرار شده است.
    
    این فیلد تنها زمانی مقداردهی می‌شود که مقدار فیلد Status برابر با Reinstated باشد؛ در غیر این صورت، مقدار آن به صورت null ارسال خواهد شد.
    
    + نمایش ویژگی‌های زیرمجموعه
    
    BookingList.PassengerList.Reinstated.Reason
    
    string
    
    این فیلد علت برقراری مجدد پرواز یا تأیید دوباره‌ی رزرو را مشخص می‌کند و شامل یکی از مقادیر زیر است:
    
    FlightReinstated
    
    بیانگر برقراری مجدد پروازی است که پیش‌تر لغو شده بود؛ در این حالت وضعیت رزرو مسافر به حالت «تأییدشده» بازمی‌گردد.
    
    IncreasedFlightCapacity
    
    بیانگر افزایش ظرفیت صندلی‌های پرواز است؛ در این حالت رزروی که به دلیل محدودیت ظرفیت (Load) غیرفعال شده بود، مجدداً معتبر و قابل استفاده می‌گردد.
    
    BookingList.PassengerList.Reinstated.FlightNumber
    
    string
    
    شماره پرواز
    
    BookingList.PassengerList.Reinstated.FlightDate
    
    datetime
    
    زمان پرواز
    
    اطلاعات زمانی داخلی این فیلد با فرمت yyyy-MM-dd HH:mm و بر اساس ناحیه زمانی فرودگاه مبدا پرواز می باشد
    
    BookingList.PassengerList.Reinstated.AirlineIataCode
    
    string
    
    یاتا کد ایرلاین
    
    BookingList.PassengerList.Reinstated.OriginIataCode
    
    string
    
    کد یاتا فرودگاه مبدا
    
    BookingList.PassengerList.Reinstated.DestinationIataCode
    
    string
    
    کد یاتا فرودگاه مقصد
  - BookingList.PassengerList.AlternativeFlightList
    
    list of AlternativeFlight
    
    فهرستی از گزینه‌های پیشنهادی برای پرواز جایگزین.
    
    اگر تأمین‌کننده پرواز در پی ابطال یا تغییر ساعت پرواز اولیه، امکان تغییر رزرو بدون جریمه و با همان نرخ قبلی (بدون مابه‌التفاوت) را برای مسافر فراهم کرده باشد، گزینه‌های پروازی در این فیلد ارائه می‌شوند. در غیر این صورت، این لیست خالی خواهد بود.
    
    + نمایش ویژگی‌های زیرمجموعه
    
    BookingList.PassengerList.AlternativeFlightList.FlightNumber
    
    string
    
    شماره پرواز
    
    BookingList.PassengerList.AlternativeFlightList.FlightDate
    
    datetime
    
    زمان پرواز
    
    اطلاعات زمانی داخلی این فیلد با فرمت yyyy-MM-dd HH:mm و بر اساس ناحیه زمانی فرودگاه مبدا پرواز می باشد
    
    BookingList.PassengerList.AlternativeFlightList.AirlineIataCode
    
    string
    
    یاتا کد ایرلاین
    
    BookingList.PassengerList.AlternativeFlightList.OriginIataCode
    
    string
    
    کد یاتا فرودگاه مبدا
    
    BookingList.PassengerList.AlternativeFlightList.DestinationIataCode
    
    string
    
    کد یاتا فرودگاه مقصد
    
    BookingList.PassengerList.AlternativeFlightList.CabinType
    
    string
    
    کابین پرواز، مثلا اکونومی یا بیزینس یا ...
  - BookingList.PassengerList.Message
    
    string
    
    متن پیام نهایی و آماده‌شده جهت اطلاع‌رسانی به مسافر.
    
    با وجود اینکه تمامی جزئیات تغییرات پرواز به صورت تفکیک‌شده در فیلدهای مربوطه ارسال شده‌اند، پیشنهاد اکید ما این است که برای ارسال پیامک، ایمیل یا نوتیفیکیشن به مسافر، مستقیماً از محتوای این فیلد استفاده کنید. بازسازی و تولید مجدد این پیام بر اساس فیلدهای دیگر، به دلیل داشتن منطق‌های تجاری (Business Logic) متعدد و استثناهای فراوان، پیچیده و زمانبر خواهد بود.
    
    در نظر داشته باشید که متن پیام Message تولید شده برای یک مسافر ممکن است متفاوت از متن پیام سایر مسافران همان رزرو باشد.

Sample Response

{
  "BookingList": [
    {
      "RecordId": 394,
      "Pnr": "S5C5K5",
      "BookingDateTimeUtc": "2026-07-18 09:06:31",
      "ChangeScheduleDateTimeUtc": "2026-07-21 07:26:16",
      "YourLocalInventoryPnr": null,
      "IsReserveIssued": true,
      "PassengerList": [
        {
          "AgeType": "ADL",
          "FirstName": "ESMAT",
          "LastName": "TAVAKOLIGARMASEH",
          "Gender": "F",
          "TicketNumber": "1549782",
          "CabinType": "Economy",
          "Status": "Cancelled",
          "Cancelled": {
            "CancellationReason": "ReducedFlightCapacityDueToOverbooking",
            "PassengerResponseDeadlineUtc": null
          },
          "FlightTimeChanged": null,
          "Reinstated": null,
          "AlternativeFlightList": [],
          "Message": "مسافر گرامی با سلام و عرض پوزش رزرو شما در پرواز 312 مورخ 30 تير 1405 مسیر آبادان به اهواز به علت کاهش ظرفیت به دلیل Over شدن باطل اعلام می گردد.\r\n\r\nجهت بازگشت وجه لطفا فرم استرداد را تکمیل نمایید."
        },
        {
          "AgeType": "ADL",
          "FirstName": "SAEID",
          "LastName": "ALISHAHIVARNOSFADERANI",
          "Gender": "M",
          "TicketNumber": "1549783",
          "CabinType": "Economy",
          "Status": "Cancelled",
          "Cancelled": {
            "CancellationReason": "ReducedFlightCapacityDueToOverbooking",
            "PassengerResponseDeadlineUtc": null
          },
          "FlightTimeChanged": null,
          "Reinstated": null,
          "AlternativeFlightList": [],
          "Message": "مسافر گرامی با سلام و عرض پوزش رزرو شما در پرواز 312 مورخ 30 تير 1405 مسیر آبادان به اهواز به علت کاهش ظرفیت به دلیل Over شدن باطل اعلام می گردد.\r\n\r\nجهت بازگشت وجه لطفا فرم استرداد را تکمیل نمایید."
        }
        // ... بیشتر مسافران
      ]
    }
    // ... بیشتر Bookingها
  ]
}

صفحه قبلی

صفحه بعدی

لیست سرویس‌ها

متد GetList

Request Parameters

Sample Request

Response Parameters

Sample Response