Skip to main content
#P1671

POST /v2/charter/reservation

Charter: Insert Bulk Reservations

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

Request Overview

URL: /v2/charter/reservation
Method: POST
Controller: CharterController@insertListCharterReservation
Middleware Stack: authWithJwt

Access Control

  • دسترسی معتبر JWT

Request Body (JSON)

Field Type Description
main_id integer (الزامی) شناسه چارتر اصلی
item_id integer (الزامی) شناسه آیتم محاسباتی (کلاس پروازی یا نوع اتاق)
checkin_date string (Y-m-d) (فقط برای اقامتگاه) تاریخ ورود
checkout_date string (Y-m-d) (فقط برای اقامتگاه) تاریخ خروج
passengers array[object] (الزامی) لیست مسافرانی که باید برایشان رزرو ثبت شود.

ساختار آبجکت Passenger

Field Type Description
identity.id string کد ملی برای مسافر ایرانی
identity.nationality string کد ۲ حرفی ISO کشور (مثلاً 'IR')
passport.id string شماره پاسپورت برای مسافر خارجی
fullname.first_name.en string نام (انگلیسی)
fullname.last_name.en string نام خانوادگی (انگلیسی)
birth string تاریخ تولد (Y-m-d)
mobile / email string اطلاعات تماس (اختیاری)
status string (اختیاری) اگر مقدار آن refund باشد، رزرو مستقیماً به عنوان استرداد ۱۰۰٪ ثبت می‌شود.
financial object (اختیاری) برای ثبت قیمت به صورت دستی. اگر ارسال نشود، قیمت به صورت خودکار محاسبه می‌شود.
  • financial.supplier: نام تأمین‌کننده
  • financial.sale_price: مبلغ قابل پرداخت
  • financial.commission: مبلغ کمیسیون

Logic Details

۱. اعتبارسنجی گسترده

پیش از هر اقدامی، سیستم تمام مسافران موجود در آرایه passengers را بررسی می‌کند. در صورت وجود اولین خطا، عملیات متوقف و کد خطای 422 Unprocessable Entity بازگردانده می‌شود.

  • ملیت: باید یک کد معتبر دو حرفی باشد (کدهای ۳ حرفی به ۲ حرفی تبدیل می‌شوند). (خطای 1019)
  • کد ملی / پاسپورت: برای ایرانیان الگوریتم کد ملی و برای خارجی‌ها فرمت پاسپورت بررسی می‌شود. (خطای 1011)
  • اطلاعات تماس: فرمت شماره موبایل و ایمیل بررسی می‌شود. (خطای 1013, 1014)
  • تاریخ تولد: باید با فرمت Y-m-d باشد. (خطای 1021)

۲. بررسی ظرفیت

پس از اعتبارسنجی، سیستم تعداد مسافران بزرگسال و کودک را شمارش کرده و با ظرفیت باقی‌مانده آیتم مقایسه می‌کند.
اگر ظرفیت کافی نباشد، عملیات متوقف و کد خطای 409 Conflict به همراه پیام "ظرفیت تکمیل است" (کد 1008) بازگردانده می‌شود.

۳. تفاوت منطق Route و Accommodation

هسته اصلی این متد بر اساس نوع چارتر عمل می‌کند:

  • نوع Route (پرواز، قطار و...):
    - برای هر مسافر در آرایه یک رزرو جداگانه ایجاد می‌شود.
    - قبل از ایجاد، بررسی می‌شود که آیا مسافر قبلاً برای همین چارتر رزرو فعال دارد یا خیر (جلوگیری از ثبت تکراری). در صورت تکراری بودن، یک آیتم خطا در خروجی نهایی قرار می‌گیرد.
  • نوع Accommodation (هتل):
    - تمام مسافران در آرایه به عنوان مهمانان یک رزرو واحد (یک اتاق) در نظر گرفته می‌شوند.
    - ابتدا بررسی می‌شود که آیا برای بازه checkin_date تا checkout_date اتاق خالی وجود دارد یا خیر. در غیر این صورت، خطای 409 Conflict (کد 1026) بازگردانده می‌شود. - پس از ایجاد رزرو، سیستم به صورت خودکار یک اتاق در دسترس را برای تمام شب‌های اقامت به این رزرو اختصاص می‌دهد.

۴. محاسبه مالی و ثبت

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

Response Structure

پاسخ موفق

در صورت موفقیت، کد 201 Created به همراه آرایه‌ای از نتایج بازگردانده می‌شود. این آرایه می‌تواند شامل آیتم‌های موفق و ناموفق (مثلاً مسافر تکراری) باشد.

{
  "items": [
    {
      "status": true,
      "pnr": {
        "local": "XG7H5A2B", // PNR مشترک برای این بچ
        "original": "K9L4M1N0", // Slug یکتای این رزرو
        "id": 10845        // شناسه رزرو + 10000
      },
      // این بخش فقط برای رزرو اقامتگاه وجود دارد
      "accommodation_rooms": [
        {
          "reservation_id": 10845,
          "room_id": 10021,
          "date": "2025-12-25",
          "number": "205"
        }
      ]
    },
    {
      "status": false,
      "item_id": 45,
      "details": "0012345678",
      "code": 1010,
      "message": "برای این مسافر قبلا این آیتم خریداری شده است.",
      "solution": "..."
    }
  ],
  "meta": { "timestamp": 1715000000 }
}

Flowchart

Start (POST /reservation)
↓
Validation Loop (Passengers):
Nationality → ID/Passport → Contact → Birth Date
Fail → Halt & Return 422
Pass ↓
Capacity Check:
Required (ADT+CHD) vs. Available Balance
Fail → Halt & Return 409
Pass ↓
Check Charter Type
Type: Route
Loop Each Passenger
↓
Check for Duplicates
↓
Create Individual Reservation
↓
Add to `insertQuery` Array
Type: Accommodation
Check Room Availability
Fail → Halt & Return 409
Pass ↓
Create One Reservation for All Guests
↓
Add to `insertQuery` Array
↓
Final Insertion Loop:
Insert DB Record → Handle Refund Status → For Accommodation, Assign Room per Night
↓
Return 201 with Result Array
Back to top