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

متد GetPassengersByDate

Download Markdown for LLM

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

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

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

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

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

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

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

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

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

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


API Endpoint

POST https://{SupplierWebsiteUrl}/api/B2M/Bot/Flight/Federated/ScheduleChanges/GetPassengersByDate/V1

Request Parameters

  • UserName

    string

    [conditional-required]

    نام کاربری

    در صورت استفاده از روش Username/Password Authentication ارسال این فیلد الزامی است.

  • Password

    string

    [conditional-required]

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

    در صورت استفاده از روش Username/Password Authentication ارسال این فیلد الزامی است.

  • AccessToken

    string

    [conditional-required]

    توکن احراز هویت دریافت‌شده از طریق Single Sign-On (SSO).

    در صورت استفاده از روش Token-based Authentication این فیلد را ارسال کنید. در این حالت نیازی به ارسال UserName و Password نیست.

    برای آشنایی با روش‌های احراز هویت و نحوه انتخاب و استفاده از هر روش، به مستندات Authentication مراجعه کنید.

  • FromDateTimeUtc

    datetime

    required

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

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

  • MessageCultureList

    List(string)

    required

    فهرست زبان‌های مورد نظر برای دریافت متن پیام اطلاع‌رسانی مسافر.

    برای هر زبانِ اعلام‌شده در این فهرست، یک آیتم در فیلد MessageList خروجی هر مسافر تولید می‌شود. مقادیر مجاز:

    • fa-IR (فارسی)
    • en-US (انگلیسی)
    • ar-IQ (عربی)

Sample Request

curl -X POST https://SepehrApiTest.ir/api/B2M/Bot/Flight/Federated/ScheduleChanges/GetPassengersByDate/V1 \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip, deflate" \
  -d '{
  "UserName": "sample-head-office-user",
  "Password": "25f9e794323b453885f5181f1b624d0b",
  "FromDateTimeUtc": "2024-02-01 00:00:00",
  "MessageCultureList": ["fa-IR", "en-US"]
}'

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.ClientLocalInventoryPnr

      string

      رفرنس سیستم داخلی رزرو گیرنده

    • BookingList.IsReserveIssued

      boolean

      این فیلد مشخص می‌کند که رزرو مسافر نهایی و صادر شده است یا همچنان در وضعیت موقت قرار دارد و هنوز صادر نشده است.

      از آنجا که در این وب‌سرویس، برای هر دو نوع رزروِ موقت (صادرنشده) و رزروِ نهایی‌شده، در صورت تغییر برنامه پروازی رکورد خروجی برگردانده می‌شود، این فیلد در پاسخ قرار داده شده است تا بتوانید وضعیت رزرو را تشخیص دهید.

      در صورتی که بخواهید بر اساس موقت یا نهایی بودن رزرو، متن یا نحوه اطلاع‌رسانی متفاوتی به مسافر ارسال کنید، می‌توانید از مقدار این فیلد استفاده کنید.

    • BookingList.ReserveForAgencyId

      integer

      شناسه منحصر به فرد آژانس طرف حساب رزرو

    • BookingList.ReserveForAgencyName

      string

      نام آژانس طرف حساب رزرو

    • BookingList.BookingPhoneNumber

      string

      شماره تلفن ثبت‌شده برای رزرو.

    • BookingList.BookingEmail

      string

      آدرس پست الکترونیک ثبت‌شده برای رزرو.

    • BookingList.AgencySupportPhoneNumber

      string

      شماره تلفن پشتیبانی پرواز آژانس طرف حساب رزرو.

      در صورتی که برای آژانس طرف حساب رزرو، شماره تلفن پشتیبانی پرواز در سیستم تعریف نشده باشد، مقدار این فیلد به صورت null ارسال می‌شود.

    • BookingList.AgencySupportEmail

      string

      آدرس پست الکترونیک پشتیبانی پرواز آژانس طرف حساب رزرو.

      در صورتی که برای آژانس طرف حساب رزرو، آدرس پست الکترونیک پشتیبانی پرواز در سیستم تعریف نشده باشد، مقدار این فیلد به صورت null ارسال می‌شود.

    • BookingList.SupplierId

      integer

      شناسه منحصر به فرد تأمین‌کننده پرواز.

      در صورتی که برای رزرو، تأمین‌کننده‌ای در سیستم ثبت نشده باشد، مقدار این فیلد به صورت null ارسال می‌شود.

    • BookingList.SupplierName

      string

      نام تأمین‌کننده پرواز.

      در صورتی که برای رزرو، تأمین‌کننده‌ای در سیستم ثبت نشده باشد، مقدار این فیلد به صورت null ارسال می‌شود.

    • 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.MessageList

        List(Message)

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

        برای هر زبانِ اعلام‌شده در فیلد MessageCultureList درخواست، یک آیتم در این لیست تولید می‌شود.

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

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

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

        • BookingList.PassengerList.MessageList.Culture

          string

          زبان متن پیام. مقدار این فیلد با یکی از مقادیر ارسال‌شده در فیلد MessageCultureList درخواست مطابقت دارد (مثلاً fa-IR، en-US یا ar-IQ).

        • BookingList.PassengerList.MessageList.Body

          string

          متن پیام نهایی و آماده‌شده جهت اطلاع‌رسانی به مسافر به زبانِ مشخص‌شده در فیلد Culture.


Sample Response

{
  "BookingList": [
    {
      "RecordId": 394,
      "Pnr": "S5C5K5",
      "BookingDateTimeUtc": "2026-07-18 09:06:31",
      "ChangeScheduleDateTimeUtc": "2026-07-21 07:26:16",
      "ClientLocalInventoryPnr": null,
      "IsReserveIssued": true,
      "ReserveForAgencyId": 2822,
      "ReserveForAgencyName": "فروش نقدي اينترنتي",
      "BookingPhoneNumber": "+989122953473",
      "BookingEmail": "sample@sample.com",
      "AgencySupportPhoneNumber": "+989352283333",
      "AgencySupportEmail": "sample@sample.com",
      "SupplierId": 15,
      "SupplierName": "نام تامین کننده تستی",
      "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": [],
          "MessageList": [
            {
              "Culture": "fa-IR",
              "Body": "مسافر گرامی با سلام و عرض پوزش رزرو شما در پرواز 312 مورخ 30 تير 1405 مسیر آبادان به اهواز به علت کاهش ظرفیت به دلیل Over شدن باطل اعلام می گردد.\r\n\r\nجهت بازگشت وجه لطفا فرم استرداد را تکمیل نمایید."
            },
            {
              "Culture": "en-US",
              "Body": "Dear passenger, we apologize for the inconvenience. Your booking on flight 312 dated 2026-09-20 from Abadan to Ahvaz has been cancelled due to reduced capacity (overbooking).\r\n\r\nPlease complete the refund form to receive your refund."
            }
          ]
        },
        {
          "AgeType": "ADL",
          "FirstName": "SAEID",
          "LastName": "ALISHAHIVARNOSFADERANI",
          "Gender": "M",
          "TicketNumber": "1549783",
          "CabinType": "Economy",
          "Status": "Cancelled",
          "Cancelled": {
            "CancellationReason": "ReducedFlightCapacityDueToOverbooking",
            "PassengerResponseDeadlineUtc": null
          },
          "FlightTimeChanged": null,
          "Reinstated": null,
          "AlternativeFlightList": [],
          "MessageList": [
            {
              "Culture": "fa-IR",
              "Body": "مسافر گرامی با سلام و عرض پوزش رزرو شما در پرواز 312 مورخ 30 تير 1405 مسیر آبادان به اهواز به علت کاهش ظرفیت به دلیل Over شدن باطل اعلام می گردد.\r\n\r\nجهت بازگشت وجه لطفا فرم استرداد را تکمیل نمایید."
            },
            {
              "Culture": "en-US",
              "Body": "Dear passenger, we apologize for the inconvenience. Your booking on flight 312 dated 2026-09-20 from Abadan to Ahvaz has been cancelled due to reduced capacity (overbooking).\r\n\r\nPlease complete the refund form to receive your refund."
            }
          ]
        }
        // ... بیشتر مسافران
      ]
    }
    // ... بیشتر Bookingها
  ]
}