# GET /v2/charter/pledger

# Charter: List Branch Pledgers

این اندپوینت لیست ضامنین (Pledgers) یک شعبه را از جدول `charter_pledgers` به همراه اطلاعات همکار (colleague) بازیابی می‌کند. داده‌ها با join روی جدول `colleagues` enrich شده و خروجی نهایی یک آرایه items با ساختار title.fa و title.en بازمی‌گرداند.

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

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fcharter%2Fple"><div class="endpoint-info"><div>**URL:** `/v2/charter/pledger`</div><div>**Method:** <span class="method-get">GET</span></div><div>**Controller:** CharterController@listPledgerCharter</div><div>**Middleware:** authWithJwt</div></div></div>## Query Parameters

<div class="api-docs" id="bkmrk-parameter-type-requi"><table class="schema-table"><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>branch</td><td>integer</td><td>yes</td><td>شناسه شعبه‌ای که باید لیست ضامنین آن واکشی شود</td></tr></tbody></table>

</div>## Database Tables

### Table: charter\_pledgers

<div class="api-docs" id="bkmrk-column-type-descript"><table class="schema-table"><thead><tr><th>Column</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>integer</td><td>شناسه ضامن</td></tr><tr><td>colleague\_id</td><td>integer</td><td>شناسه همکار ضامن</td></tr><tr><td>branch</td><td>integer</td><td>شناسه شعبه</td></tr><tr><td>status</td><td>tinyint</td><td>1=فعال، 0=غیرفعال</td></tr></tbody></table>

</div>### Table: colleagues

<div class="api-docs" id="bkmrk-column-type-descript-1"><table class="schema-table"><thead><tr><th>Column</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>integer</td><td>شناسه همکار</td></tr><tr><td>first\_name</td><td>string</td><td>نام</td></tr><tr><td>last\_name</td><td>string</td><td>نام خانوادگی</td></tr><tr><td>office</td><td>string</td><td>نام دفتر به فارسی</td></tr><tr><td>office\_en</td><td>string</td><td>نام دفتر به انگلیسی</td></tr><tr><td>status</td><td>tinyint</td><td>باید 1 باشد تا همکار معتبر محسوب شود</td></tr></tbody></table>

</div>## Core Processing Logic

```
$pledgers = DB::table('charter_pledgers')
    ->select(
        'charter_pledgers.id',
        'colleagues.id as colleague_id',
        'colleagues.first_name',
        'colleagues.last_name',
        'colleagues.office',
        'colleagues.office_en',
        'colleagues.status'
    )
    ->where('charter_pledgers.branch', $request->get('branch'))
    ->where('charter_pledgers.status', 1)
    ->where('colleagues.status', 1)
    ->leftJoin('colleagues', 'charter_pledgers.colleague_id', 'colleagues.id')
    ->orderBy('charter_pledgers.id', 'DESC')
    ->get();
  
```

<div class="api-docs" id="bkmrk-%D9%81%D9%82%D8%B7-%D8%B6%D8%A7%D9%85%D9%86%DB%8C%D9%86-%D9%81%D8%B9%D8%A7%D9%84-bran">- فقط ضامنین فعال branch مدنظر انتخاب می‌شوند
- leftJoin تضمین می‌کند اگر colleague حذف شده باشد، رکورد pledger حذف نشود (اما فیلتر status=1 جلوی آن را می‌گیرد)
- مرتب‌سازی DESC بر اساس آخرین ضامن‌های ثبت‌شده انجام می‌شود

</div>## Output Mapping Logic

```
$return = $pledgers->map(function ($pledger) {
    return [
        'id' => $pledger->id,
        'colleague_id' => $pledger->colleague_id,
        'title' => [
            'fa' => $pledger->office .
                   ($pledger->last_name != '' 
                     ? ' ' . $pledger->first_name . ' ' . $pledger->last_name 
                     : ""),
            'en' => $pledger->office_en
        ]
    ];
});
  
```

ساختار title.fa مطابق الگوی زیر ساخته می‌شود:

<div class="api-docs" id="bkmrk-field-example-descri"><table class="schema-table"><thead><tr><th>Field</th><th>Example</th><th>Description</th></tr></thead><tbody><tr><td>office</td><td>آژانس هرمس</td><td>نام دفتر</td></tr><tr><td>first\_name</td><td>علی</td><td>نام همکار (در صورت وجود)</td></tr><tr><td>last\_name</td><td>کاظمی</td><td>نام خانوادگی همکار (در صورت وجود)</td></tr><tr><td colspan="3">**Final Output Example →** آژانس هرمس علی کاظمی</td></tr></tbody></table>

</div>## Response (Success)

```
{
  "items": [
    {
      "id": 18,
      "colleague_id": 92,
      "title": {
        "fa": "آژانس هرمس علی کاظمی",
        "en": "Hermes Agency"
      }
    }
  ],
  "meta": { "timestamp": 1710000000 }
}
  
```

<div class="api-docs" id="bkmrk--1"></div>## Response (Error)

```
{
  "message": "SQLSTATE[HY000]: ...",
  "trace": [...]
}
  
```

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

<div class="api-docs" id="bkmrk-validate-jwt-%E2%86%93-read-"><div class="flowchart"><div class="flow-item">Validate JWT</div><div class="flow-arrow">↓</div><div class="flow-item">Read Query Param: branch</div><div class="flow-arrow">↓</div><div class="flow-item">DB Query charter_pledgers WHERE branch, status=1</div><div class="flow-arrow">↓</div><div class="flow-item">LEFT JOIN colleagues ON colleague_id</div><div class="flow-arrow">↓</div><div class="flow-item">Filter colleagues.status=1</div><div class="flow-arrow">↓</div><div class="flow-item">ORDER BY id DESC</div><div class="flow-arrow">↓</div><div class="flow-item">Map → Build title.fa / title.en</div><div class="flow-arrow">↓</div><div class="flow-item">Return JSON: items[], meta.timestamp</div></div></div>