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