# GET /v2/credit-card

# Credit Card: Show Details

این اندپوینت برای **مشاهده جزئیات یک کارت اعتباری خاص** استفاده می‌شود.   
ویژگی منحصر‌به‌فرد این متد، **حساسیت به مالکیت (Ownership Awareness)** است. سیستم بررسی می‌کند که آیا درخواست‌کننده (Operator) همان صاحب کارت است یا خیر. اگر مالک باشد، اطلاعات محرمانه (CVV2، تاریخ انقضا و شماره کامل) نمایش داده می‌شود؛ در غیر این صورت، داده‌ها ماسک می‌شوند.

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

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fcredit-card"><div class="endpoint-info"><div>**URL:** `/v2/credit-card`</div><div>**Method:** <span class="method-get">GET</span></div><div>**Controller:** CreditCards@showCreditCard</div><div>**Middleware:** authWithJwt</div></div></div>## Access Control

<div class="api-docs" id="bkmrk-%D9%86%DB%8C%D8%A7%D8%B2-%D8%A8%D9%87-%D8%AA%D9%88%DA%A9%D9%86-%D8%A7%D8%AD%D8%B1%D8%A7%D8%B2-%D9%87">- نیاز به توکن احراز هویت (JWT).
- دسترسی به اطلاعات کامل (CVV2/Expire) فقط مخصوص **صاحب کارت** است.

</div>## Query Parameters

<div class="api-docs" id="bkmrk-parameter-type-descr"><div class="table-wrapper"><table class="schema-table" dir="rtl"><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>integer</td><td>**(اختیاری\*)** شناسه منحصر‌به‌فرد کارت اعتباری. (معمولاً یا این فیلد یا `passenger_id` باید ارسال شود).</td></tr><tr><td>passenger\_id</td><td>integer</td><td>**(اختیاری\*)** شناسه مسافر. برای یافتن کارت فعال یک مسافر خاص استفاده می‌شود.</td></tr></tbody></table>

</div></div>\* توجه: اگرچه پارامترها اختیاری (Optional) تعریف شده‌اند، اما برای دریافت خروجی معتبر باید حداقل یکی از آن‌ها ارسال شود تا کوئری نتیجه‌ای برگرداند.

<div class="api-docs" id="bkmrk--1"></div>## Logic Details &amp; Security

منطق پردازش شامل مراحل زیر است:

<div class="api-docs" id="bkmrk-%D8%AC%D8%B3%D8%AA%D8%AC%D9%88-%D9%88-%D8%A7%D8%AA%D8%B5%D8%A7%D9%84-%28query">1. **جستجو و اتصال (Query &amp; Join):**
    - جستجو در جدول `credit_cards` بر اساس `id` یا `passenger_id`.
    - اتصال (Left Join) به جدول `customers` برای دریافت نام مسافر.
    - دریافت اولین رکورد منطبق (`first()`).
2. **بررسی مالکیت (Ownership Check):**
    - سیستم شناسه کاربری که لاگین کرده (`$request->operator->id`) را با شناسه صاحب کارت (`passenger_id`) مقایسه می‌کند.
3. **سطح‌بندی نمایش داده‌ها (Visibility Logic):**
    - **حالت ۱: کاربر مالک کارت است**
        - شماره کارت: **کامل** نمایش داده می‌شود (از دیتابیس خوانده می‌شود).
        - فیلدهای حساس: `cvv2` و `expire_date` به پاسخ اضافه می‌شوند.
    - **حالت ۲: کاربر مالک نیست (مثلاً ادمین یا اپراتور دیگر)**
        - شماره کارت: توسط تابع `Functions::creditCardSecurity` **ماسک** می‌شود.
        - فیلدهای حساس: `cvv2` و `expire_date` **ارسال نمی‌شوند**.

</div>## Response Structure

### حالت اول: پاسخ به مالک کارت (Owner View)

```json
{
  "payload": {
    "id": 105,
    "status": 1,
    "card": {
      "number": "6219861012345678", // Full Number
      "withdrawal_limit": false,
      "blocked_amount": false,
      "cvv2": "452",              // Visible
      "expire_date": "1405/02"    // Visible
    },
    "passenger": {
      "id": 2045,
      "first_name": "علی",
      "last_name": "محمدی"
    }
  },
  "meta": { "timestamp": 1715005000 }
}
```

### حالت دوم: پاسخ به سایرین (Admin/Public View)

```json
{
  "payload": {
    "id": 105,
    "status": 1,
    "card": {
      "number": "6219********5678", // Masked Number
      "withdrawal_limit": false,
      "blocked_amount": false
      // CVV2 and Expire Date are OMITTED
    },
    "passenger": {
      "id": 2045,
      "first_name": "علی",
      "last_name": "محمدی"
    }
  },
  "meta": { "timestamp": 1715005000 }
}
```

### خطای ۴۲۲ (پیدا نشد)

اگر با پارامترهای ارسالی کارتی پیدا نشود:

```json
{
  "error": {
    "code": 1000,
    "message": "کارت اعتباری پیدا نشد."
  },
  "meta": { ... }
}
```

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

<div class="api-docs" id="bkmrk-start-request-%E2%86%93-find"><div class="flowchart"><div class="flow-item">Start Request</div><div class="flow-arrow">↓</div><div class="flow-item-process">Find Card (ID or PassengerID)</div><div class="flow-arrow">↓</div><div class="flow-item-decision">Found?</div><div style="display: flex; justify-content: flex-end; width: 60%; margin: -20px auto 20px;"><div style="text-align: center;"><div class="flow-arrow-label-right" style="font-size: 12px; color: red;">No</div><div class="flow-item-process" style="background-color: #ffebee; border-color: #ef9a9a;">Return 422 Error</div></div></div><div class="flow-arrow" style="margin-top: -10px;">↓ Yes</div><div class="flow-item-decision">Is Operator == Passenger?</div><div style="display: flex; justify-content: space-between; margin-top: 20px; direction: ltr;"><div style="width: 48%;"><div class="flow-arrow-label-left" style="text-align: center; color: #2e7d32; font-weight: bold;">Yes (Owner)</div><div class="flow-item-process" style="background-color: #e8f5e9;">**Full Access**  
Show Full Number  
Add CVV2 &amp; Expire</div></div><div style="width: 48%; border-left: 2px dashed #ccc; padding-left: 10px;"><div class="flow-arrow-label-right" style="text-align: center; color: #f57c00; font-weight: bold;">No (Admin)</div><div class="flow-item-process" style="background-color: #fff3e0;">**Restricted Access**  
Mask Number (****)  
Hide Sensitive Data</div></div></div><div class="flow-arrow">↓</div><div class="flow-item-success">Return JSON Payload</div></div></div>