# RESOURCE /v2/cartable/letters

<div class="api-docs" id="bkmrk-">  <div class="endpoint-section">  
</div></div>## Letter &amp; Workflow Logic

ماژول کارتابل دارای یک منطق گردش کار (Workflow) است. زمانی که یک نامه ایجاد می‌شود، سیستم به صورت خودکار اولین مرحله (Step) آن فرآیند را ایجاد می‌کند. همچنین زمانی که وضعیت یک مرحله به "انجام شده" تغییر می‌کند، سیستم به صورت هوشمند مرحله بعدی را تشخیص داده و ایجاد می‌کند.

<div class="api-docs" id="bkmrk-create-letter-reques"><div class="endpoint-section"><div class="flowchart"><div class="flow-item">Create Letter Request</div><div class="flow-arrow">↓</div><div class="flow-item-process" style="background-color: #fff3e0;">**Step 1: Initialization**  
Generate Serial ID  
Insert Letter Record</div><div class="flow-arrow">↓</div><div class="flow-item-process" style="background-color: #e3f2fd;">**Step 2: Workflow Trigger**  
Fetch `cartable_subjects` (Process Config)  
Decode `steps` JSON  
**Insert First Step** into `cartable_letter_steps`</div><div class="flow-arrow">↓</div><div class="flow-item-success">Return Letter Resource</div></div></div>  
---

  </div># Get Letters List

دریافت لیست نامه‌های موجود در کارتابل. این متد از یک سیستم صفحه‌بندی (Pagination) خاص استفاده می‌کند که پارامترهای `length` و `start` را به شماره صفحه لاراول تبدیل می‌کند.

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fcartable%2Fle"><div class="endpoint-info"><div>**URL:** `/v2/cartable/letters`</div><div>**Method:** <span class="method-get">GET</span></div><div>**Controller:** LetterController@index</div></div></div>### Query Parameters

<div class="api-docs" id="bkmrk-parameter-type-descr"><table class="schema-table" dir="rtl"><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td dir="ltr">paginate\[length\]</td><td>Integer</td><td>(اختیاری) تعداد آیتم در هر صفحه (پیش‌فرض: 30).</td></tr><tr><td dir="ltr">paginate\[start\]</td><td>Integer</td><td>(اختیاری) آفست شروع دیتا (برای محاسبه صفحه فعلی).</td></tr><tr><td dir="ltr">requester\_id</td><td>Integer</td><td>(اختیاری) فیلتر بر اساس شناسه درخواست‌کننده.</td></tr><tr><td dir="ltr">subject</td><td>Integer</td><td>(اختیاری) فیلتر بر اساس شناسه موضوع نامه.</td></tr><tr><td dir="ltr">status</td><td>Integer</td><td>(اختیاری) فیلتر بر اساس وضعیت کلی نامه.</td></tr></tbody></table>

</div>### Response Structure

خروجی توسط `LetterResource` فرمت‌دهی می‌شود.

```json
{
    "items": [
        {
            "id": 50,
            "serial": "LET-1402-001",
            "subject": { "id": 1, "title": "Leave Request" },
            "requester": { "id": 10, "name": "Ali..." },
            "current_step": { "id": 205, "status": "pending" },
            "created_at": "..."
        }
    ],
    "meta": { "timestamp": 1733754000 }
}
```

<div class="api-docs" id="bkmrk--1">---

  </div># Create Letter

ایجاد یک نامه جدید.   
**نکته مهم:** پس از ایجاد نامه، سیستم به جدول `cartable\_subjects` مراجعه کرده و لیست مراحل تعریف شده برای آن موضوع (`subject`) را می‌خواند و به صورت خودکار **اولین مرحله** را در جدول `cartable\_letter\_steps` برای این نامه ثبت می‌کند.

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fcartable%2Fle-1"><div class="endpoint-info"><div>**URL:** `/v2/cartable/letters`</div><div>**Method:** <span class="method-post">POST</span></div><div>**Controller:** LetterController@store</div></div></div>### Body Parameters

<div class="api-docs" id="bkmrk-parameter-type-descr-1"><table class="schema-table" dir="rtl"><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td dir="ltr">branch</td><td>Integer</td><td>(الزامی) شناسه شعبه (برای تولید شماره سریال).</td></tr><tr><td dir="ltr">subject</td><td>Integer</td><td>(الزامی) شناسه موضوع نامه (تعیین کننده مراحل گردش کار).</td></tr><tr><td dir="ltr">recipient</td><td>String</td><td>(اختیاری) گیرنده نامه.</td></tr><tr><td dir="ltr">title</td><td>String</td><td>(اختیاری) عنوان نامه.</td></tr><tr><td dir="ltr">description</td><td>String</td><td>(اختیاری) توضیحات نامه.</td></tr><tr><td dir="ltr">operators</td><td>Array\[Int\]</td><td>(اختیاری) لیست اپراتورهای دخیل (به صورت JSON ذخیره می‌شود).</td></tr></tbody></table>

</div>### Success Response

```json
{
    "payload": {
        "id": 51,
        "serial": "100-2569",
        "subject": 5,
        "steps": [ ... ] // شامل اولین مرحله ایجاد شده
    },
    "meta": { "timestamp": 1733754000 }
}
```

<div class="api-docs" id="bkmrk--2">---

  </div># Show Letter Details

مشاهده جزئیات کامل یک نامه. اگر نامه حذف شده باشد (`deleted\_at` داشته باشد) یا وجود نداشته باشد، خطای 404 برمی‌گرداند.

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fcartable%2Fle-2"><div class="endpoint-info"><div>**URL:** `/v2/cartable/letters/{id}`</div><div>**Method:** <span class="method-get">GET</span></div><div>**Controller:** LetterController@show</div></div>---

  </div># Update Letter

ویرایش اطلاعات عمومی نامه (عنوان، گیرنده، توضیحات و...). این متد مراحل گردش کار را تغییر نمی‌دهد.

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fcartable%2Fle-3"><div class="endpoint-info"><div>**URL:** `/v2/cartable/letters/{id}`</div><div>**Method:** <span class="method-put">PUT</span> / <span class="method-patch">PATCH</span></div><div>**Controller:** LetterController@update</div></div></div>### Body Parameters

<div class="api-docs" id="bkmrk-parameter-type-descr-2"><table class="schema-table" dir="rtl"><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td dir="ltr">title</td><td>String</td><td>عنوان نامه.</td></tr><tr><td dir="ltr">subject</td><td>Integer</td><td>تغییر موضوع نامه.</td></tr><tr><td dir="ltr">operators</td><td>Array\[Int\]</td><td>لیست اپراتورها.</td></tr><tr><td dir="ltr">description</td><td>String</td><td>توضیحات.</td></tr><tr><td dir="ltr">recipient</td><td>String</td><td>گیرنده.</td></tr></tbody></table>

---

  </div># Delete Letter

حذف نرم (Soft Delete) نامه. فیلد `deleted_at` با زمان فعلی مقداردهی می‌شود.

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fcartable%2Fle-4"><div class="endpoint-info"><div>**URL:** `/v2/cartable/letters/{id}`</div><div>**Method:** <span class="method-delete">DELETE</span></div><div>**Controller:** LetterController@destroy</div></div>---

  </div># Update Step &amp; Advance Workflow

**توجه:** این متد در کنترلر وجود دارد اما روت آن در اسنیپت ارائه شده نیست (احتمالاً روت سفارشی دارد).   
این متد برای تغییر وضعیت یک **مرحله (Step)** استفاده می‌شود.   
**منطق هوشمند:** اگر وضعیت ارسالی برابر با `3` (انجام شده) باشد، سیستم به صورت خودکار مرحله بعدی فرآیند را از تنظیمات موضوع (`subject steps`) پیدا کرده و آن را ایجاد می‌کند.

<div class="api-docs" id="bkmrk-method-url%3A-%28custom-"><div class="endpoint-info"><div>**Method URL:** `(Custom Route) /v2/cartable/steps/{id}`</div><div>**Target ID:** شناسه مرحله (cartable_letter_steps.id)</div><div>**Controller:** LetterController@updateLetterStep</div></div></div>### Body Parameters

<div class="api-docs" id="bkmrk-parameter-type-descr-3"><table class="schema-table" dir="rtl"><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td dir="ltr">status</td><td>Integer</td><td>(الزامی) وضعیت جدید مرحله (مثلاً 3 برای اتمام).</td></tr><tr><td dir="ltr">description</td><td>String</td><td>(اختیاری) توضیحات یا دستور انجام کار روی مرحله.</td></tr></tbody></table>

<div class="flowchart"><div class="flow-item">Update Step Request</div><div class="flow-arrow">↓</div><div class="flow-item-process">Update `status` &amp; `description`</div><div class="flow-arrow">↓</div><div class="flow-item-decision">Status == 3 ?</div><div class="flow-arrow-right">YES →</div><div class="flow-item-process" style="background-color: #c8e6c9; margin-left: 20px;">Find Current Step Index  
Check for Next Step in Config  
**Insert Next Step**</div></div></div>