# RESOURCE /v2/scrumboard/cards

<div class="api-docs" id="bkmrk-">  <div class="endpoint-section">  
</div></div>## Card Deep Hydration Logic

کارت‌ها قلب سیستم اسکرام هستند. در تمامی متدها (Index, Store, Show, Update)، پس از دریافت اطلاعات خام کارت، یک فرآیند سنگین برای بارگذاری تمام وابستگی‌ها اجرا می‌شود. این فرآیند شامل دیکد کردن JSONها و کوئری‌های متعدد به جداول مختلف است.

<div class="api-docs" id="bkmrk-fetch-card%28s%29-data-%E2%86%93"><div class="endpoint-section"><div class="flowchart"><div class="flow-item">Fetch Card(s) Data</div><div class="flow-arrow">↓</div><div class="flow-item-process" style="background-color: #fff3e0;">**Step 1: JSON Fields**  
Decode `members` &amp; `labels`  
Fetch Operators &amp; Label Objects via IDs</div><div class="flow-arrow">↓</div><div class="flow-item-process" style="background-color: #e3f2fd;">**Step 2: Sub-Entities**  
1. Get Comments (+ Hydrate Operators)  
2. Get Checklists (+ Hydrate Operators + Decode Items)  
3. Get Attachments (Media table)  
4. Get Sprints (JSON Search)</div><div class="flow-arrow">↓</div><div class="flow-item-success">Return Fully Hydrated Card</div></div></div>  
---

  </div># Get Cards List

دریافت لیست کارت‌های موجود در یک لیست (ستون) خاص. تمامی اطلاعات وابسته (اعضا، لیبل‌ها، پیوست‌ها و...) به همراه کارت برگردانده می‌شوند.

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fscrumboard%2F"><div class="endpoint-info"><div>**URL:** `/v2/scrumboard/cards`</div><div>**Method:** <span class="method-get">GET</span></div><div>**Controller:** CardController@index</div></div></div>### Parameters

<div class="api-docs" id="bkmrk-parameter-type-locat"><table class="schema-table" dir="rtl"><thead><tr><th>Parameter</th><th>Type</th><th>Location</th><th>Description</th></tr></thead><tbody><tr><td dir="ltr">list\_id</td><td>Integer</td><td>Query</td><td>(الزامی) شناسه لیست (ستون) والد.</td></tr><tr><td dir="ltr">status</td><td>Integer</td><td>Query</td><td>(اختیاری) فیلتر وضعیت کارت.</td></tr></tbody></table>

</div>### Response Structure

```json
{
    "items": [
        {
            "id": 101,
            "list_id": 5,
            "title": "Fix Login Bug",
            "description": "User cannot login with email...",
            "members": [
                { "id": 1, "first_name": "Ali", "avatar": "..." }
            ],
            "labels": [
                { "id": 2, "title": "Bug", "color": "#ff0000" }
            ],
            "comments": [ ... ], // لیست کامل نظرات با اطلاعات نویسنده
            "checklists": [ ... ], // لیست چک‌لیست‌ها با آیتم‌ها
            "attachments": [ ... ], // مدیاهای متصل
            "sprints": [ ... ], // اسپرینت‌های مرتبط
            "created_at": "..."
        }
    ],
    "meta": { "timestamp": 1733754000 }
}
```

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

  </div># Create Card

ایجاد یک کارت جدید ساده. پس از ایجاد، کارت بلافاصله بازیابی شده و ساختار کامل (با آرایه‌های خالی برای وابستگی‌ها) برگردانده می‌شود.

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fscrumboard%2F-1"><div class="endpoint-info"><div>**URL:** `/v2/scrumboard/cards`</div><div>**Method:** <span class="method-post">POST</span></div><div>**Controller:** CardController@store</div></div></div>### 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">list\_id</td><td>Integer</td><td>شناسه لیست مقصد.</td></tr><tr><td dir="ltr">title</td><td>String</td><td>عنوان کارت.</td></tr></tbody></table>

</div>### Success Response

```json
{
    "payload": {
        "id": 102,
        "title": "New Feature",
        "members": [],
        "labels": [],
        "comments": [],
        "checklists": [],
        "attachments": [],
        "sprints": [],
        ...
    },
    "meta": { "timestamp": 1733754000 }
}
```

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

  </div># Show Card Details

دریافت جزئیات کامل یک کارت با شناسه مشخص.

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fscrumboard%2F-2"><div class="endpoint-info"><div>**URL:** `/v2/scrumboard/cards/{id}`</div><div>**Method:** <span class="method-get">GET</span></div><div>**Controller:** CardController@show</div></div></div>### Response

اگر کارت پیدا نشود، `payload: false` برمی‌گرداند.

```json
{
    "payload": {
        "id": 101,
        "title": "Fix Login Bug",
        "members": [ ... ],
        "checklists": [
            {
                "id": 5,
                "title": "QA",
                "checkitems": [{ "text": "Test A", "done": true }],
                "operator": { ... }
            }
        ],
        ...
    },
    "meta": { "timestamp": 1733754000 }
}
```

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

  </div># Update Card &amp; Sub-Resources

این متد علاوه بر آپدیت فیلدهای اصلی کارت، قابلیت **مدیریت تو‌در‌توی (Nested Management)** برای `comments` و `checklists` را نیز دارد. شما می‌توانید همزمان با ویرایش کارت، یک کامنت یا چک‌لیست را ایجاد، ویرایش یا حذف کنید.

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fscrumboard%2F-3"><div class="endpoint-info"><div>**URL:** `/v2/scrumboard/cards/{id}`</div><div>**Method:** <span class="method-put">PUT</span> / <span class="method-patch">PATCH</span></div><div>**Controller:** CardController@update</div></div></div>### Basic 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">list\_id</td><td>Integer</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">due\_date</td><td>Date/String</td><td>تاریخ سررسید.</td></tr><tr><td dir="ltr">members</td><td>Array\[Int\]</td><td>لیست جدید شناسه‌های اعضا (جایگزین کل لیست قبلی می‌شود).</td></tr><tr><td dir="ltr">labels</td><td>Array\[Int\]</td><td>لیست جدید شناسه‌های لیبل‌ها.</td></tr><tr><td dir="ltr">done\_at</td><td>DateTime</td><td>زمان انجام شدن.</td></tr><tr><td dir="ltr">status</td><td>Integer</td><td>وضعیت (پیش‌فرض 1).</td></tr></tbody></table>

</div>### Advanced Parameters (Nested Actions)

ارسال این پارامترها اختیاری است و برای عملیات سریع روی زیرمجموعه‌ها استفاده می‌شود.

#### 1. مدیریت کامنت (پارامتر `comment`)

<div class="api-docs" id="bkmrk-action-payload-struc"><table class="schema-table" dir="rtl"><thead><tr><th>Action</th><th>Payload Structure</th></tr></thead><tbody><tr><td>**Create**</td><td dir="ltr">`{ "card_id": 1, "operator_id": 2, "message": "text" }`  
(بدون ارسال id)</td></tr><tr><td>**Delete**</td><td dir="ltr">`{ "id": 10, "delete": true }`</td></tr></tbody></table>

</div>#### 2. مدیریت چک‌لیست (پارامتر `checklist`)

<div class="api-docs" id="bkmrk-action-payload-struc-1"><table class="schema-table" dir="rtl"><thead><tr><th>Action</th><th>Payload Structure</th></tr></thead><tbody><tr><td>**Create**</td><td dir="ltr">`{ "card_id": 1, "title": "Checklist 1", "checkitems": [...] }`  
(بدون ارسال id)</td></tr><tr><td>**Update**</td><td dir="ltr">`{ "id": 5, "card_id": 1, "title": "New Title", "checkitems": [...] }`</td></tr><tr><td>**Delete**</td><td dir="ltr">`{ "id": 5, "delete": true }`</td></tr></tbody></table>

</div>### Success Response

```json
{
    "payload": {
        "id": 101,
        // کارت آپدیت شده به همراه تمام تغییرات اعمال شده در کامنت‌ها/چک‌لیست‌ها
        "comments": [ ... ], 
        "checklists": [ ... ],
        ...
    },
    "meta": { "timestamp": 1733754000 }
}
```

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

  </div># Delete Card

حذف کارت از دیتابیس. توجه: طبق کد فعلی، وابستگی‌ها (مثل کامنت‌ها) به صورت Cascade در کد PHP حذف نمی‌شوند مگر اینکه در سطح دیتابیس تنظیم شده باشد.

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fscrumboard%2F-4"><div class="endpoint-info"><div>**URL:** `/v2/scrumboard/cards/{id}`</div><div>**Method:** <span class="method-delete">DELETE</span></div><div>**Controller:** CardController@destroy</div></div></div>### Success Response

```json
{
    "payload": 1, // 1: موفق، 0: ناموفق
    "meta": { "timestamp": 1733754000 }
}
```