Skip to main content
#P1714

GET /v2/credit-card/index

Credit Card: List & Index

این اندپوینت وظیفه واکشی و نمایش لیست کارت‌های اعتباری صادر شده را بر عهده دارد.
اطلاعاتمهم‌ترین درویژگی این لیستبخش، شاملاعمال وضعیت کارت، مشخصات مسافر و محدودیت‌های مالی است. نکته مهملایه‌ی امنیتی این اندپوینت، ماسک کردن (Masking)روی شماره کارت‌هاست،ها به(Masking) طوریجهت کهحفاظت تنهااز ۴داده‌های رقم ابتداییحساس و انتهاییهمچنین قابلفیلترینگ مشاهدههوشمند هستند.بر اساس دسترسی شعبه (Branch Access) می‌باشد.

Request Overview

URL: /v2/credit-card/index
Method: GET
Controller: CreditCards@indexCreditCard
Middleware: authWithJwt

Access Control

  • نیاز به توکن احراز هویت (JWT).
  • پاسخ‌داده‌ها بر اساس پارامتر branch فیلتر می‌شوند (دسترسیایزوله‌سازی شعبه)داده‌های شعب).

Query Parameters

Parameter Type Description
branch integer (الزامی) شناسه شعبه.شعبه درخواست‌کننده. اگر مقدارکاربر غیرادمین ازمرکزی 1نباشد، باشد، نتایج فیلتر می‌شوند تالیست فقط کارت‌هایمحدود مرتبطبه بارکوردهای آناین شعبه نمایش داده شوند.می‌شود.
paginate[length] integer (الزامی) تعداد آیتم‌هارکورد مورد نظر در هر صفحه (Limit).
paginate[start] integer (الزامی) نقطهآفست (Offset) شروع رکوردهارکوردها. (Offset).سیستم از این عدد برای محاسبه شماره صفحه فعلی استفاده می‌شود.کند.

Logic Details

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

  1. فیلترینگکنترل سطح دسترسی شعبه (AccessBranch Policy)Filtering):
    • اگرسیستم پارامتربررسی می‌کند که آیا branch ارسال شده برابر با 1 نباشد (شعبه غیردفتر مرکزی)، است یا خیر.
    • اگر branch != 1 باشد، شرط whereJsonContains('branch', $branch) به کوئری اضافه می‌شود. این یعنی یک کوئری روی ستون JSON branch اجرا می‌شود.
    • از دستور whereJsonContains استفاده می‌شود تا اطمینان حاصل شود کارت متعلقممکن است به چند شعبه درخواست‌کنندهدسترسی است.داشته باشد (ساختار JSON).
  2. تجمعغنی‌سازی داده‌ها (Data Aggregation)Enrichment):
    • جدول credit_cards با جدول customers (به صورت Left Join)Join ترکیب می‌شود.
    • هدف از این جوین،هدف: استخراج نام و نام خانوادگی فارسی مسافر (`first_name_fa`, `last_name_fa`) صاحبجهت کارتنمایش است.در لیست.
  3. محاسبه صفحه‌بندی دستی (Pagination Calculation)Logic):
    • شمارهلاراول صفحهبه فعلیصورت (Current Page)پیش‌فرض با page کار می‌کند، اما ورودی دیتاتیبل معمولاً start و length است.
    • فرمول زیرتبدیل: محاسبه$page می‌شود:=
      ($start == 0 ? $length : $start + $length) / $length
    • سپس متد paginate لاراول با شماره صفحه محاسبه شده فراخوانی می‌گردد..
  4. لایه امنیت و تغییر شکل داده‌هافرمت (TransformationSecurity & Security)Transformation):
    • ماسک کردن شماره کارت: تابع Functions::creditCardSecurity اجرافراخوانی می‌شود.
      فرمتالگوریتم: خروجی:نمایش 4۴ رقم اول + ستاره (*)******* + 4نمایش ۴ رقم آخر.
      مثال:نتیجه: 6037*6219********1234.
    • مدیریت مقادیر Null:خالی: فیلدهای withdrawal_limit و blocked_amount چکبررسی می‌شوند؛ اگر نالnull باشند، مقدار false برگردانده می‌شود.شود تا در فرانت‌اند خطای تایپ رخ ندهد.

Response Structure

پاسخ موفق (200 OK)

{
  "items": [
    {
      "id": 105,
      "status": 1, // 1: Active, 0: Inactive
      "card": {
        "number": "6219********4321", // Masked for security
        "withdrawal_limit": false,      // false if null
        "blocked_amount": 500000
      },
      "passenger": {
        "id": 2045,
        "first_name": "علی",
        "last_name": "محمدی"
      }
    }
    // ... more items
  ],
  "meta": {
    "timestamp": 1715005000,
    "table": {
      "total": 50,
      "per_page": 10,
      "current_page": 1,
      "last_page": 5,
      "from": 1,
      "to": 10
    }
  }
}

پاسخمدیریت خطا

(Exception)

در صورت بروز خطای دیتابیس یا منطقی، ساختار زیر برای دیباگ برگردانده می‌شود:

{
  "error": {
    "code": "42S22"HY000", // SQL Error Code
    "message": "ColumnSQLSTATE[HY000]: notGeneral found.error: ...",
    "file": "/app/Http/Controllers/V2/CreditCards.php",
    "line": 4585
  },
  "meta": { "timestamp": 17150012001715005123 }
}

Flowchart

Start Request
Is Branch == 1?
No (Specific Branch)
Add Filter Query
whereJsonContains(branch)'branch', id)
Yes (Admin)HQ)
No Filter Applied
Execute Query Database
Left Join Customers table
CalculateApply Page NumberPagination
Transform Data Transformation
1. Mask Card Number (****)
2. Format PassengerResponse ObjJSON
Return JSON200 ListOK