Skip to main content
#P1715

GET /v2/credit-card

Credit Card: Show Details

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

Request Overview

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

Access Control

  • نیاز به توکن احراز هویت (JWT).
  • دسترسی به اطلاعات کامل (CVV2/Expire) فقط مخصوص صاحب کارت است.

Query Parameters

Parameter Type Description
id integer (اختیاری*) شناسه منحصر‌به‌فرد کارت اعتباری. (معمولاً یا این فیلد یا passenger_id باید ارسال شود).
passenger_id integer (اختیاری*) شناسه مسافر. برای یافتن کارت فعال یک مسافر خاص استفاده می‌شود.

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

Logic Details & Security

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

  1. جستجو و اتصال (Query & 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 ارسال نمی‌شوند.

Response Structure

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

{
  "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)

{
  "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 }
}

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

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

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

Flowchart

Start Request
↓
Find Card (ID or PassengerID)
↓
Found?
No
Return 422 Error
↓ Yes
Is Operator == Passenger?
Yes (Owner)
Full Access
Show Full Number
Add CVV2 & Expire
No (Admin)
Restricted Access
Mask Number (****)
Hide Sensitive Data
↓
Return JSON Payload
Back to top