POST /v2/credit-card

Credit Card: Issue Request 

 این اندپوینت وظیفه احراز هویت پیشرفته و صدور کارت اعتباری برای مسافر را بر عهده دارد. در این فرآیند، اطلاعات هویتی و مالکیتی سیم‌کارت از طریق سرویس‌های شاهکار و ثبت‌احوال (Jibit) استعلام شده و در صورت تأیید، یک کارت بانکی مجازی با الگوریتم استاندارد بانکی تولید و ۵۰,۰۰۰ ریال از کیف پول اپراتور کسر می‌گردد. 

 

 Request Overview 

 

 

 URL: /v2/credit-card 

 Method: POST 

 Controller: CreditCards@createCreditCard 

 Middleware: authWithJwt 

 

 

 Access Control 

 

 

 نیاز به توکن احراز هویت (JWT). 

 اپراتور باید دسترسی به شعبه (`branch`) ارسال شده را داشته باشد. 

 

 

 Body Parameters 

 

 

 

 

 Field 

 Type 

 Description 

 

 

 

 

 passenger 

 integer 

 (الزامی) شناسه مسافر (Customer ID) که باید در سیستم فعال باشد و نام/نام خانوادگی فارسی داشته باشد. 

 

 

 branch 

 integer 

 (الزامی) شناسه شعبه صادرکننده (جهت تولید پیش‌شماره کارت). 

 

 

 mobile 

 string 

 (اختیاری) شماره موبایل جهت استعلام مالکیت. اگر ارسال نشود، از شماره موبایل پروفایل مسافر استفاده می‌شود. 

 

 

 identity_code 

 string 

 (اختیاری) کدملی جهت استعلام. اگر ارسال نشود، از کدملی پروفایل مسافر استفاده می‌شود. 

 

 

 operator 

 object 

 (تزریق سیستمی) آبجکت اپراتور که معمولاً توسط میدل‌ور به ریکوئست اضافه می‌شود (جهت ثبت در تراکنش کیف پول). 

 

 

 

 

 Logic Details 

 فرآیند صدور کارت دارای منطق پیچیده اعتبارسنجی به شرح زیر است: 

 

 

 اعتبارسنجی اولیه: 

 

 مسافر باید وجود داشته باشد، وضعیت آن فعال (`status=1`) باشد و نام/نام‌خانوادگی فارسی پر شده باشد. 

 فرمت شماره موبایل و کد ملی (الگوریتم چک‌دیجیت) بررسی می‌شود. 

 بررسی تکراری نبودن: اگر مسافر از قبل کارت فعال (وضعیت ۱ یا ۳) داشته باشد، خطا بازگردانده می‌شود. 

 

 

 استعلام تطابق هویتی (Jibit Identity Check): این مرحله تنها در صورتی اجرا می‌شود که مسافر قبلاً احراز نشده باشد (`identity_check IS NULL`). 

 

 سرویس getIdentitySimilarity فراخوانی می‌شود. 

 اگر درصد تشابه نام و نام خانوادگی کمتر از 90% باشد، خطا بازگردانده می‌شود. 

 نتیجه استعلام در دیتابیس مشتری (`identity_check` و `identity_data`) کش می‌شود. 

 

 

 استعلام مالکیت سیم‌کارت (Shahkar): 

 

 سرویس getMatchingService برای تطابق کدملی و موبایل فراخوانی می‌شود. 

 در صورت عدم تطابق مالکیت، فرآیند متوقف شده و خطا برمی‌گردد. 

 

 

 تولید شماره کارت (Luhn Algorithm): 

 

 پیش‌شماره (BIN): بر اساس کد شعبه ساخته می‌شود. اگر شعبه >= 90 باشد: 990 + branch+10 در غیر این صورت: 9900 + branch+10 

 ساختار: [BIN] + [AccountType:1] + [PassengerID:9digits] 

 ارقام باقی‌مانده تصادفی تولید شده و رقم آخر (Check Digit) با فرمول Luhn محاسبه می‌شود. 

 CVV2 تصادفی و انقضا ۳ ساله تنظیم می‌شود. 

 

 

 عملیات مالی و ذخیره‌سازی: 

 

 ثبت کارت در جدول credit_cards . 

 کسر مبلغ 50,000 ریال از کیف پول اپراتور با عنوان "بابت استعلام هویت مسافر". 

 ارسال پیامک اطلاع‌رسانی به مسافر از طریق صف fastJob . 

 

 

 

 

 Response Structure 

 پاسخ موفق 

 

 

 Status Code: 201 Created 

 Body: Empty (بدون محتوا). 

 

 

 پاسخ‌های خطا (نمونه) 

 {

 "error": {

 "code": 1000, // یا کدهای خطای جیبیت

 "message": "اطلاعات هویتی مسافر با اطلاعات هویتی موجود در سیستم ثبت احوال مطابقت ندارد."

 },

 "meta": {

 "timestamp": 1715001200

 }

} 

 کدهای وضعیت HTTP: 

 

 

 422 Unprocessable Entity : خطای اعتبارسنجی ورودی، نقص اطلاعات پروفایل یا عدم تطابق هویتی. 

 500 Internal Server Error : خطای سیستمی یا خطای اتصال به جیبیت. 

 

 

 Flowchart 

 

 

 Start Request 

 ↓ 

 Validate Inputs & Passenger Profile 

 ↓ 

 Card Exists? 

 

 Yes 

 Error: Active Card 

 

 ↓ (No) 

 Identity Check is Null? 

 

 

 

 Yes 

 Jibit Identity API Check Name Similarity 

 Similiarity > 90%? 

 (No) -> Error 422 

 

 

 No (Already Checked) 

 

 

 ↓ 

 Jibit Shahkar API Match Mobile & NationalCode 

 Match OK? 

 

 No 

 Error: Ownership 

 

 ↓ (Yes) 

 Generate Card Calc BIN + Luhn Check Digit 

 ↓ 

 Finalize 1. Insert Card 2. Deduct Wallet (50k) 3. Queue SMS 

 ↓ 

 Return 201 Created