تفاوت استعلام شبا با تبدیل کارت به شبا در سه نقطه است: ورودی، خروجی و هدف. استعلام شبا با شماره شبا شروع می‌شود و صحت، مالکیت و وضعیت حساب را برمی‌گرداند؛ تبدیل کارت به شبا با شماره کارت ۱۶ رقمی شروع می‌شود و شماره شبا متناظر را استخراج می‌کند. این دو، endpoint جدا، قرارداد داده جدا و جایگاه جدا در محصول دارند و جایگزین هم نیستند.
پاسخ سریع: این دو سرویس را یکی فرض نکنید
تعریف یک‌خطی استعلام شبا: ورودی شماره شبا استاندارد با پیشوند IR است و خروجی، اعتبارسنجی همراه با نام صاحب حساب، نام بانک و وضعیت حساب است. تعریف یک‌خطی تبدیل کارت به شبا: ورودی شماره کارت ۱۶ رقمی است و خروجی اصلی، شماره شبای متناظر همان حساب است.
| معیار | استعلام شبا | تبدیل کارت به شبا |
|---|---|---|
| ورودی | شماره شبا (IR…) | شماره کارت ۱۶ رقمی |
| خروجی اصلی | اعتبارسنجی، نام صاحب حساب، نام بانک، وضعیت حساب | استخراج شماره شبا (و در صورت پاسخ سرویس، اطلاعات تکمیلی حساب) |
| هدف اصلی | تأیید صحت و مالکیت شبای موجود | کشف/بازیابی شبا وقتی فقط کارت در دست است |
| مرحله استفاده در محصول | بعد از جمع‌آوری شبا؛ KYC، ثبت حساب تسویه، کنترل قبل از واریز | ورود داده؛ وقتی کاربر فقط کارت دارد و هنوز شبا مشخص نیست |
تفاوت API استعلام شبا و کارت به شبا را از همین جدول بخوانید: استعلام شبا وقتی استفاده می‌شود که از قبل شبا را دارید و می‌خواهید صحت و مالکیت آن را بررسی کنید. مرز استعلام شبا و تبدیل کارت همین‌جاست؛ یکی‌پنداری این دو، انتخاب endpoint اشتباه را قطعی می‌کند.
استعلام شبا چیست و چه مسئله‌ای را در جریان پرداخت حل می‌کند؟
استعلام شبا چیست؟ سرویسی برای اعتبارسنجی و غنی‌سازی هویت حساب بانکی، وقتی شماره شبا از قبل در اختیار تیم یا کاربر است. برخلاف ابزارهای کشف شناسه، اینجا هدف «پیدا کردن شبا» نیست؛ هدف این است که شبای اعلام‌شده واقعاً قابل اتکا باشد و قبل از ذخیره یا واریز، مالک و وضعیت حساب روشن شود.
ورودی الزامی، شماره شبا استاندارد با ساختار IR است. خروجی هدفمند شامل صحت ساختار و وجود شبا، نام صاحب یا صاحبان حساب، نام بانک و وضعیت حساب است. در مستندات فنی، وضعیت‌هایی مثل فعال، مسدود با قابلیت واریز، مسدود بدون قابلیت واریز، راکد یا نامشخص دیده می‌شود؛ همین فیلدها منطق کسب‌وکار را تغذیه می‌کنند.
کاربرد استعلام شماره شبا در API برای تیم‌های فین‌تک، PSP و پرداخت‌یار مشخص است: onboarding پذیرنده، ثبت حساب تسویه، کنترل مالکیت قبل از واریز، و کاهش برگشت وجه ناشی از حساب اشتباه یا حساب غیرقابل واریز. جایگاه این سرویس در قیف محصول بعد از جمع‌آوری شبا است، نه در مرحله‌ای که هنوز باید شبا را از روی کارت کشف کرد.
برای عمق تصمیم‌گیری معماری، این کلاستر را کنار وب سرویس API استعلام شماره شبا؛ مرجع تصمیم‌گیری فنی برای فین‌تک، PSP و تیم محصول بخوانید. پایه معنایی خوشه همین‌جاست: استعلام، تأیید شبای موجود است.
تبدیل کارت به شبا چه می‌کند و چرا نباید با استعلام یکی گرفته شود؟
تبدیل کارت به شبا سرویس جداگانه‌ای است: ورودی شماره کارت ۱۶ رقمی است و کار اصلی‌اش نگاشت کارت به شماره شبای متناظر همان حساب است. هدف اصلی تبدیل، کشف یا بازیابی شباست وقتی کاربر یا پذیرنده فقط کارت دارد و هنوز شناسه شبا در فرم یا دیتابیس شما نیست.
تفاوت هدف را قاطع نگه دارید. تبدیل یعنی شناسایی شبا از روی کارت. استعلام یعنی تأیید و غنی‌سازی شبایی که از قبل دارید. حتی اگر پاسخ برخی سرویس‌های تبدیل فیلدهای تکمیلی حساب را هم برگرداند، قرارداد ورودی، endpoint و نقطه تصمیم محصول یکی نیست. API استعلام شبا در مقابل تبدیل، دو مدل داده و دو نقطه فراخوانی معماری می‌سازد.
عبارت‌هایی مثل تبدیل شماره شبا به کارت یا تبدیل شبا به حساب، متعلق به خانواده تبدیل و نگاشت شناسه‌اند. این‌ها جایگزین استعلام مالکیت و وضعیت حساب برای شبای موجود نمی‌شوند. اگر تیم محصول فقط به‌خاطر شباهت اسمی «شبا» این دو را در یک سرویس داخلی ادغام کند، مرز معنایی از بین می‌رود و تست قرارداد هم بی‌معنا می‌شود.
تفاوت ورودی و خروجی استعلام شبا؛ جدول تصمیم‌گیری برای انتخاب endpoint
تفاوت ورودی خروجی استعلام شبا در برابر تبدیل، از سطح پارامتر شروع می‌شود. استعلام، مقدار شبا با پیشوند IR می‌گیرد. تبدیل، شماره کارت ۱۶ رقمی می‌گیرد. خروجی استعلام روی هویت و وضعیت حساب متمرکز است: بانک، نام بانک، وضعیت، نام وضعیت، شماره حساب، شبا و آرایه صاحبان حساب. خروجی تبدیل حول استخراج رشته شبا از کارت شکل می‌گیرد و endpoint آن مسیر دیگری است.
| سؤال تصمیم | پاسخ معماری | endpoint مناسب |
|---|---|---|
| همین حالا شبا دارم و باید صحت/مالکیت را ببینم؟ | تأیید قبل از ذخیره یا واریز | استعلام شبا |
| فقط کارت ۱۶ رقمی دارم و شبا هنوز معلوم نیست؟ | کشف شناسه شبا | تبدیل کارت به شبا (مسیر جدا) |
| در KYC یا ثبت حساب تسویه هستم؟ | کنترل حساب اعلام‌شده | استعلام شبا |
| در ورود داده اولیه و فرم فقط کارت می‌گیرم؟ | تکمیل شناسه حساب | تبدیل، سپس در صورت نیاز استعلام روی شبای به‌دست‌آمده |
چه زمانی از استعلام شبا استفاده کنیم؟ وقتی شبا جمع شده و باید قبل از commit داده حساس یا قبل از واریز تأیید شود. هدف اصلی استعلام صحت‌سنجی و مالکیت است؛ هدف تبدیل استخراج شناسه. ریسک یکی‌پنداری مستقیم است: schema دیتابیس غلط، نام‌گذاری سرویس مبهم، و تست قرارداد ناقص که در محیط واقعی onboarding یا تسویه خودش را نشان می‌دهد.
مرجع فنی فیلدها و نمونه درخواست/پاسخ API استعلام شبا
این بخش فقط قرارداد استعلام شبا است و نباید با پاسخ تبدیل کارت اشتباه گرفته شود. احراز هویت با هدر Authorization به‌صورت Bearer accessToken و نوع محتوا application/json انجام می‌شود.
ورودی
| محل | نام | نوع | توضیح |
|---|---|---|---|
| Header | Content-Type | application/json | نوع بدنه درخواست |
| Header | Authorization | Bearer accessToken | توکن دسترسی |
| Query | value | string | شماره شبا |
نمونه فراخوانی:
GET https://api.novin.one/v1/ibans?value=IR123456789012345678901234خروجی
| فیلد | نوع | توضیح |
|---|---|---|
| bank | string | شناسه بانک مربوط به شماره حساب |
| bankName | string | نام خوانای بانک |
| status | string | یکی از مقادیر: Active (فعال)، DEPOSIT_WITH_BLOCK (حساب مسدود است اما قابلیت واریز دارد)، BLOCK_WITHOUT_DEPOSIT (حساب مسدود شده و قابلیت واریز ندارد)، IDLE (حساب راکد است)، UNKNOWN (نامشخص) |
| statusName | string | ترجمه وضعیت حساب |
| iban | string | شماره شبا |
| depositNumber | string | شماره حساب |
| owners | Owner[] | آرایه صاحب/صاحبان حساب |
| فیلد owners | نوع | توضیح |
|---|---|---|
| firstName | string | نام |
| lastName | string | نام خانوادگی |
برای منطق کسب‌وکار، ذخیره حساب تسویه را به ترکیبی از موفقیت پاسخ، وجود owners و وضعیت قابل‌قبول واریز گره بزنید. وضعیت مسدود بدون واریز یا راکد معمولاً نباید به مرحله commit نهایی برسد. خطاهای مستند این سرویس شامل مواردی مثل شبا الزامی، شبا نامعتبر، شبا یافت نشد، صاحب شبا یافت نشد، توکن غیرمجاز، رسیدن به محدودیت روزانه، در دسترس نبودن سرویس‌دهنده و خطای داخلی سرور است. جزئیات مدیریت خطا و کدهای وضعیت را داخل همین خوشه پیگیری کنید؛ قرارداد تبدیل کارت را اینجا قاطی نکنید.
معیارهای ارزیابی یکپارچه‌سازی برای تیم محصول، PSP و پرداخت‌یار
نقطه فراخوانی درست، بعد از دریافت شبا و قبل از commit داده حساس است. در onboarding پذیرنده یا ثبت حساب تسویه، فرم شبا را بگیرید، استعلام را بزنید، نتیجه را با قواعد کسب‌وکار بسنجید، بعد ذخیره کنید. زودتر از موعد فراخوانی کردن، یا وابسته کردن کشف شبا به همین endpoint، طراحی را کج می‌کند.
امنیت فراخوانی در محیط فین‌تک حداقل روی توکن دسترسی، حداقل سطح دسترسی و عدم افشای کلید در کلاینت عمومی استوار است. برای مسیرهای پرترافیک onboarding، محدودیت نرخ و الگوی retry امن را از روز اول در معماری ببینید؛ خطاهایی مثل رسیدن به محدودیت روزانه باید مسیر محصول مشخص داشته باشند، نه فقط لاگ خام.
مدل هزینه هر استعلام را در واحد اقتصاد محصول حساب کنید: هر ثبت حساب، هر تغییر حساب تسویه، و هر کنترل مجدد قبل از واریزهای حساس. قابلیت اطمینان و SLA روی نرخ رها شدن فرم ثبت حساب اثر مستقیم دارد؛ اگر استعلام در لحظه حساس قطع شود، کاربر در میانه onboarding می‌ماند.
مراحل یکپارچه‌سازی در سطح معماری این‌هاست: قفل کردن قرارداد داده استعلام، نگاشت فیلدها به دیتابیس (شبا، وضعیت، نام بانک، owners)، تست منفی برای شبا نامعتبر و صاحب یافت‌نشده، و مانیتورینگ نرخ خطا. نمونه کد و مستندات فنی را فقط از هم‌خوشه استعلام شبا بگیرید، نه از سرویس‌های کارت‌به‌شبا.
هشدار معماری: یکی فرض کردن استعلام و تبدیل چه هزینه‌ای می‌سازد؟
انتخاب endpoint اشتباه دو شکل رایج دارد: ارسال شماره کارت به استعلام شبا، یا انتظار فیلدهای تصمیم‌ساز مالکیت و وضعیت از سرویسی که فقط برای استخراج شناسه در جریان ورود داده طراحی شده است. هر دو، تست را سبز و تولید را معیوب می‌کنند.
طراحی دیتابیس نادرست معمولاً این‌طور شروع می‌شود: فقط رشته شبا ذخیره می‌شود بدون وضعیت اعتبار و مالکیت؛ یا برعکس، مدل داده به کارت قفل می‌شود در حالی که تسویه روی شبا است. نتیجه، گزارش‌های ناقص و تصمیم‌های عملیاتی بدون پشتوانه است.
شکست منطق کسب‌وکار گران‌تر است. واریز به حساب تأییدنشده، یا بلاک شدن onboarding به‌خاطر سرویس نامرتبط، مستقیم به برگشت وجه، تیکت پشتیبانی و توقف عملیات PSP یا پرداخت‌یار می‌رسد. هزینه مهاجرت بعدی هم کم نیست: تغییر قرارداد API، بازنویسی SDK، اصلاح داده تاریخی و downtime تست.
چک‌لیست تصمیم کوتاه است. آیا همین حالا شبا دارم؟ بله؛ استعلام. فقط کارت دارم؟ مسیر تبدیل جدا. کاربرد استعلام شبا را با خانواده تبدیل قاطی نکنید تا کانیبالیزیشن معنایی در محصول و در مستندات داخلی رخ ندهد.
جایگاه این کلاستر در مرجع تصمیم‌گیری استعلام شماره شبا
جمع‌بندی مرزها یک جمله است: ورودی متفاوت، هدف متفاوت، خروجی متفاوت. استعلام شبا برای تأیید شبای موجود است؛ تبدیل کارت برای وقتی است که شبا را هنوز ندارید. این مقاله کلاستر مقایسه‌ای داخل خوشه استعلام شماره شباست و باید تصمیم endpoint را قبل از قفل معماری روشن کند.
مسیر صعودی برای تصمیم فنی کامل، همان مرجع تصمیم‌گیری وب سرویس API استعلام شماره شبا است. مسیرهای بعدی داخل خوشه: مستندات فنی، نمونه کد، مدیریت خطا. قبل از قفل معماری onboarding و تسویه، قرارداد استعلام شبا را با فیلدها و خطاهای واقعی ارزیابی کنید.
سوالات پرتکرار
تفاوت استعلام شبا با تبدیل کارت به شبا دقیقاً چیست؟
روی سه محور: ورودی، خروجی، هدف. استعلام از شماره شبا به اعتبار، مالکیت و وضعیت حساب می‌رود. تبدیل از کارت ۱۶ رقمی به استخراج شماره شبا می‌رود. endpointها قابل جایگزینی نیستند و قرارداد داده یکی نیست.
استعلام شبا چیست و چه خروجی‌ای می‌دهد؟
سرویس تأیید حساب وقتی شبا از قبل موجود است. ورودی IR است. خروجی شامل اعتبارسنجی، نام صاحب حساب، نام بانک، وضعیت حساب، شماره حساب و خود شبا است. برای کشف شبا از کارت ساخته نشده است.
چه زمانی از استعلام شبا استفاده کنیم و چه زمانی تبدیل کارت؟
اگر شبا را دارید و صحت یا مالکیت می‌خواهید، استعلام. اگر فقط کارت ۱۶ رقمی دارید و باید شبا را به دست آورید، تبدیل. در onboarding و تسویه، بعد از داشتن شبا همیشه استعلام را برای کنترل قبل از ذخیره یا واریز ببینید.
آیا می‌توان با شماره کارت، استعلام شبا گرفت؟
خیر، به‌صورت مستقیم. ورودی استعلام شبا است. کارت متعلق به قرارداد تبدیل است. یکی‌کردن این دو باعث خطای معماری و انتخاب endpoint غلط می‌شود.
تفاوت ورودی و خروجی API استعلام شبا با سرویس تبدیل چیست؟
ورودی استعلام: IR. ورودی تبدیل: کارت ۱۶ رقمی. خروجی استعلام: هویت و وضعیت حساب. خروجی اصلی تبدیل: رشته شبا. هدف استعلام تأیید است؛ هدف تبدیل استخراج شناسه.
اگر این دو سرویس را یکی فرض کنیم چه خطری برای محصول دارد؟
endpoint اشتباه، schema نادرست، منطق تسویه معیوب، و هزینه مهاجرت بعدی. برای تیم محصول و معماری یعنی onboarding شکننده، داده تاریخی کثیف و بازنویسی قرارداد در بدترین زمان.
نتیجه‌گیری
تفاوت استعلام شبا با تبدیل کارت به شبا را در طراحی سیستم جدی بگیرید: یکی تأیید شبای موجود است، دیگری استخراج شبا از کارت. اگر در حال طراحی onboarding پذیرنده یا حساب تسویه هستید، endpoint را با سؤال «آیا همین حالا شبا دارم؟» انتخاب کنید، نه با شباهت اسمی. برای ارزیابی قرارداد، نمونه پاسخ و جای درست سرویس در معماری، صفحه وب سرویس api استعلام شماره شبا را ببینید و قبل از قفل نهایی، فیلدها و خطاها را با جریان واقعی محصول تطبیق دهید.
