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 

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

 

 

 جستجو و اتصال (Query & Join): 

 

 جستجو در جدول credit_cards بر اساس id یا passenger_id . 

 اتصال (Left Join) به جدول customers برای دریافت نام مسافر. 

 دریافت اولین رکورد منطبق ( first() ). 

 

 

 بررسی مالکیت (Ownership Check): 

 

 سیستم شناسه کاربری که لاگین کرده ( $request->operator->id ) را با شناسه صاحب کارت ( passenger_id ) مقایسه می‌کند. 

 

 

 سطح‌بندی نمایش داده‌ها (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