# PUT /v2/charter

# Charter: Update Inventory (Operation)

این اندپوینت مسئول مدیریت تغییرات یک چارتر ثبت‌شده است. این متد یک **Action Dispatcher** داخلی دارد که بر اساس مقدار `action` درخواست را به یکی از سه رفتار مستقل هدایت می‌کند: `base`، `calculations` و `copy`. این عملیات‌ها اتمیک و تحت تراکنش انجام می‌شوند و سیستم از **Capacity Protection** برای جلوگیری از تناقض ظرفیت و فروش استفاده می‌کند.

<div class="api-docs" id="bkmrk-"></div>## Request Overview

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fcharter-met"><div class="endpoint-info" dir="ltr"><div>**URL:** /v2/charter</div><div>**Method:** PUT</div><div>**Controller:** CharterController@operationCharter</div><div>**Middleware:** authWithJwt</div></div></div>## Key Features &amp; Behavior

<div class="api-docs" id="bkmrk-action-based-logic%3A-">- **Action-Based Logic:** سه مسیر عملیاتی مستقل (Base, Calculations, Copy).
- **Capacity Protection:** ظرفیت جدید نمی‌تواند کمتر از تعداد رزروهای قطعی/موقت باشد.
- **Transactional:** هر عملیات کامل در یک تراکنش انجام می‌شود.
- **Deep Cloning:** در حالت Copy تمام جداول وابسته با Serial جدید تکثیر می‌شوند.
- **Financial Sync:** مالیات، کمیسیون، قوانین استرداد و اتاق‌ها برای هر کلاس نرخی مدیریت می‌شود.

</div>## Payload Schema (Root Level)

<div class="api-docs" id="bkmrk-field-type-required-"><table class="schema-table" dir="rtl"><thead><tr><th>Field</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>action</td><td>string</td><td>Yes</td><td dir="rtl">مقدار ثابت: `base` یا `calculations` یا `copy`</td></tr><tr><td>id</td><td>int</td><td>Cond.</td><td dir="rtl">شناسه چارتر (برای base و copy الزامی است)</td></tr><tr><td>main\_id</td><td>int</td><td>Cond.</td><td dir="rtl">شناسه چارتر (در حالت calculations الزامی است)</td></tr><tr><td>items</td><td>array</td><td>Cond.</td><td dir="rtl">برای calculations مورد نیاز است</td></tr></tbody></table>

</div>## Logic 1: Base Operation

این حالت برای ویرایش اطلاعات عمومی چارتر استفاده می‌شود.

<div class="api-docs" id="bkmrk-field-type-descripti"><table class="schema-table" dir="rtl"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>status</td><td>bool</td><td>فعال/غیرفعال</td></tr><tr><td>capacity</td><td>int</td><td>ظرفیت کلی (چک ظرفیت اعمال می‌شود)</td></tr><tr><td>commission</td><td>float</td><td>کمیسیون پایه</td></tr><tr><td>get\_passenger</td><td>bool</td><td>نیاز به اطلاعات مسافر</td></tr><tr><td>notification</td><td>object</td><td>{ mobile, text, date, time }</td></tr></tbody></table>

</div>```
// Capacity Guard Example
$cap = CharterHelper::capacityItemCharter($id);
if ($new_capacity < $cap['reserved_total']) {
    throw new Exception("New capacity cannot be lower than sold seats.");
}
  
```

<div class="api-docs" id="bkmrk--1"></div>## Logic 2: Calculations Operation

مدیریت کلاس‌های نرخی، قیمت‌ها، ظرفیت اتاق‌ها، مالیات‌ها و قوانین کنسلی.

<div class="api-docs" id="bkmrk-create%3A-%D8%A7%DB%8C%D8%AC%D8%A7%D8%AF-%DA%A9%D9%84%D8%A7%D8%B3-%D8%AC">- `create`: ایجاد کلاس جدید
- `update`: ویرایش قیمت/ظرفیت (با چک فروش)
- `delete`: حذف کلاس (تنها اگر فروش نداشته باشد)

</div>```
{
  "action": "calculations",
  "main_id": 150,
  "items": [
    {
      "mode": "update",
      "id": 455,
      "price": 3200000,
      "capacity": 12,
      "taxes": [{ "amount": 10000, "description": "Tax" }],
      "rules": [{ "percent": 30, "from_time": 0, "to_time": 12 }]
    }
  ]
}
  
```

<div class="api-docs" id="bkmrk--2"></div>## Logic 3: Copy Operation

عملیات کپی یک چارتر شامل:

<div class="api-docs" id="bkmrk-%D8%AA%D9%88%D9%84%DB%8C%D8%AF-serial-%D8%AC%D8%AF%DB%8C%D8%AF-%DA%A9%D9%BE">- تولید Serial جدید
- کپی جدول اصلی Charter
- کپی Charter Items
- کپی Calculations + Taxes + Rules
- کپی Mapping ها و وابستگی‌ها

</div>```
{
  "action": "copy",
  "id": 150
}
  
```

<div class="api-docs" id="bkmrk--3"></div>## Execution Flowchart

<div class="api-docs" id="bkmrk-start-%28put%29-%E2%86%93-valida"><div class="flowchart" dir="rtl"><div class="flow-item">Start (PUT)</div><div class="flow-arrow">↓</div><div class="flow-item">Validate Action</div><div class="flow-arrow">↓</div><div class="flow-item">Switch(action)</div><div class="flow-arrow">↓</div><div class="flow-item">Execute Base | Calc | Copy</div><div class="flow-arrow">↓</div><div class="flow-item">Commit Transaction</div><div class="flow-arrow">↓</div><div class="flow-item">Return Response</div></div></div>## Response Example

```
// Success
{
  "status": true,
  "data": { "id": 150, "status": true }
}

// Error
{
  "status": false,
  "message": "Capacity cannot be less than sold seats"
}
  
```

`