#P1684
POST /v2/charter/warranty
Charter: Manage Warranties (Batch Operation)
این اندپوینت به عنوان یک ابزار مدیریتی جامع برای گارانتیهای یک چارتر عمل میکند. با استفاده از متد POST، این اندپوینت قادر است در یک فراخوانی، لیستی از عملیات ایجاد، بهروزرسانی و حذف را بر روی گارانتیها انجام دهد. این رویکرد دستهای، نیاز به ارسال درخواستهای متعدد را از بین برده و مدیریت گارانتیها را بسیار کارآمد میکند.
این اندپوینت به خصوص برای چارترهای اقامتگاهی، دارای منطقهای اعتبارسنجی پیچیدهای است تا از تداخل گارانتی با رزروهای موجود جلوگیری کند.
Request Overview
URL:
/v2/charter/warrantyMethod: POST
Controller: CharterController@operationWarrantyCharter
Middleware Stack: authWithJwt
Access Control
- دسترسی معتبر JWT
Request Body Structure
بدنه درخواست از سه بخش اصلی تشکیل شده است: main_id برای شناسایی چارتر، آرایه warranties برای عملیات ایجاد و بهروزرسانی، و آرایه deleted برای عملیات حذف.
| Field | Type | Description |
|---|---|---|
| main_id | integer | (الزامی) شناسه اصلی چارتر (charter_main.id) که گارانتیها به آن تعلق دارند. |
| warranties | array of objects | (الزامی) آرایهای از اشیاء گارانتی. هر شیء میتواند یک گارانتی جدید برای ایجاد یا یک گارانتی موجود برای بهروزرسانی باشد. ساختار داخلی آن در جدول زیر توضیح داده شده است. |
| deleted | array of integers | (اختیاری) آرایهای از شناسههای گارانتی (charter_warranties.id) که باید حذف شوند. |
Structure of a Warranty Object (inside `warranties` array)
| Field | Type | Description |
|---|---|---|
| id | integer | string | شناسه عملیات: - برای ایجاد (Create): این فیلد را ارسال نکنید یا یک شناسه موقت رشتهای (مثلاً UUID) ارسال کنید. - برای بهروزرسانی (Update): شناسه عددی گارانتی موجود را ارسال کنید. |
| item_id | integer | شناسه آیتم چارتر (کلاس پرواز یا نوع اتاق) که گارانتی به آن تعلق دارد. |
| guarantor | object | شیء حاوی اطلاعات گارانتیکننده (همکار). مثال: {"id": 12} |
| warranty | object | شیء حاوی جزئیات ظرفیت و قیمت گارانتی شده برای هر رده سنی (adult, child, infant). هر رده شامل number (تعداد) و price است. |
| sank_cost | numeric | (اختیاری) هزینه سوخت شده (Sunk Cost). |
| service_price | numeric | (اختیاری) قیمت خدمات اضافی. |
| start_date | string | (اختیاری، برای اقامتگاهی) تاریخ شروع بازه گارانتی. فرمت: YYYY-MM-DD. |
| end_date | string | (اختیاری، برای اقامتگاهی) تاریخ پایان بازه گارانتی. فرمت: YYYY-MM-DD. |
| room_id | array of objects | (اختیاری، برای اقامتگاهی) آرایهای از اتاقهای گارانتی شده. هر شیء شامل room_id و number (شماره اتاق) است. برای عملیات بهروزرسانی، اتاقهای جدید در این آرایه قرار میگیرند. |
| deleted_room_id | array of objects | (اختیاری، فقط برای بهروزرسانی اقامتگاهی) آرایهای از اتاقهایی که باید از گارانتی حذف شوند. ساختار مشابه room_id. |
| status | integer | وضعیت گارانتی (مثلاً 1 برای فعال). |
Example Request (Create, Update & Delete)
{
"main_id": 451,
"warranties": [
{
"id": "temp-12345", // CREATE new warranty
"item_id": 101,
"guarantor": { "id": 25 },
"warranty": {
"adult": { "number": 10, "price": 1200000 },
"child": { "number": 5, "price": 900000 }
},
"status": 1
},
{
"id": 88, // UPDATE existing warranty
"guarantor": { "id": 26 },
"warranty": {
"adult": { "number": 2, "price": 2500000 },
"child": { "number": 0, "price": 0 }
},
"start_date": "2025-12-10",
"end_date": "2025-12-15",
"room_id": [ // Add this new room
{ "room_id": 305, "number": "305" }
],
"deleted_room_id": [ // Remove this old room
{ "room_id": 301, "number": "301" }
],
"status": 1
}
],
"deleted": [92, 95] // DELETE these two warranties
}Logic Details
منطق این اندپوینت به سه بخش اصلی تقسیم میشود که به ترتیب اجرا میشوند:
1. پردازش آرایه `warranties` (ایجاد و بهروزرسانی)
سیستم روی هر آیتم در آرایه warranties حلقه میزند و بر اساس وجود یا عدم وجود id عددی، تصمیم به ایجاد یا بهروزرسانی میگیرد.
- عملیات ایجاد (Create):
- شرط:
idوجود ندارد یا یک رشته است. - اعتبارسنجی حیاتی (برای اقامتگاهی): قبل از درج، سیستم بررسی میکند که آیا هیچ یک از اتاقهای مشخص شده (
room_id) در بازه زمانی (start_date,end_date) قبلاً در جدولcharter_reservation_accommodation_roomsرزرو شدهاند یا خیر. - در صورت تداخل: اگر حتی یک رزرو پیدا شود، عملیات متوقف شده و خطای
409 Conflictبا پیام "اتاق های انتخاب شده دارای رزرو می باشند" بازگردانده میشود. - درج داده: در صورت عدم تداخل، رکورد جدید در
charter_warrantiesو رکوردهای مرتبط درcharter_warranty_accommodation_rooms(در صورت وجود) درج میشوند.
- شرط:
- عملیات بهروزرسانی (Update):
- شرط:
idیک مقدار عددی است. - رکورد اصلی در
charter_warrantiesبا دادههای جدید بهروز میشود. - مدیریت اتاقها (برای اقامتگاهی):
- افزودن اتاق جدید: برای هر اتاق در آرایه
room_id، سیستم ابتدا بررسی میکند که آیا این اتاق هماکنون رزرو شده یا قبلاً به این گارانتی لینک شده است یا خیر. تنها در صورتی که هیچکدام از این دو شرط برقرار نباشد، اتاق جدید به گارانتی اضافه میشود. - حذف اتاق: برای هر اتاق در آرایه
deleted_room_id، لینک آن از جدولcharter_warranty_accommodation_roomsحذف میشود.
- افزودن اتاق جدید: برای هر اتاق در آرایه
- شرط:
2. پردازش آرایه `deleted` (حذف)
- شرط: آرایه
deletedوجود دارد و خالی نیست. - اعتبارسنجی حیاتی: قبل از حذف، سیستم بررسی میکند که آیا هیچ یک از شناسههای گارانتی موجود در آرایه
deleted، در جدول رزروها (charter_reservations) به عنوانwarrantyثبت شدهاند یا خیر. - در صورت وجود رزرو: اگر گارانتی مورد نظر برای ثبت حتی یک رزرو استفاده شده باشد، قابل حذف نیست. عملیات متوقف شده و خطای
409 Conflictبا پیام "آیتم های انتخاب شده دارای رزرو می باشند" بازگردانده میشود. این کار از نقض یکپارچگی دادهها جلوگیری میکند. - حذف داده: در صورت عدم وجود رزرو، رکوردهای گارانتی از جدول
charter_warrantiesو تمام لینکهای اتاق مرتبط با آن ازcharter_warranty_accommodation_roomsحذف میشوند.
Response Structure
پاسخ موفق
اگر تمام عملیاتها (ایجاد، بهروزرسانی، حذف) بدون خطا انجام شوند، پاسخ 204 No Content بازگردانده میشود.
- Status Code:
204 No Content
پاسخهای خطا (Conflict)
- Status Code:
409 Conflict
سناریو ۱: تلاش برای گارانتی کردن اتاقی که قبلاً رزرو شده است.
سناریو ۲: تلاش برای حذف گارانتی که دارای رزروهای فعال است.{ "error": { "code": 1000, "message": "اتاق های انتخاب شده دارای رزرو می باشند." } }
{ "error": { "code": 1000, "message": "آیتم های انتخاب شده دارای رزرو می باشند." } }