API استعلام شبا: راهنمای فنی کامل برای توسعه‌دهندگان و کسب‌وکارها

اگر تا حالا مجبور شدی برای تأیید یک شماره حساب بانکی به صورت دستی با بانک تماس بگیری، می‌دانی که این فرآیند چقدر کند و پرخطاست. API استعلام شبا دقیقاً برای حل همین مشکل آمده: اتوماسیون تأیید اطلاعات بانکی در لحظه، بدون دخالت انسانی. این راهنما برای توسعه‌دهنده‌ای نوشته شده که می‌خواهد این سرویس را پیاده‌سازی کند، و برای مدیر محصولی که باید تصمیم بگیرد کجا و چطور از api استعلام شبا استفاده کند.

API استعلام شبا چه اطلاعاتی برمی‌گرداند و چرا اهمیت دارد؟

سرویس استعلام شبا با دریافت یک شماره IBAN بانکی، چند دسته اطلاعات حیاتی برمی‌گرداند. اول و مهم‌تر از همه، نام و نام خانوادگی صاحب حساب. بعد از آن، نام بانک و شعبه مرتبط، نوع حساب (جاری، پس‌انداز، قرض‌الحسنه) و وضعیت فعال یا غیرفعال بودن حساب. همین چهار دسته اطلاعات است که یک سیستم پرداخت را از حدس و گمان نجات می‌دهد.

اما یک نکته مهم را باید از اول روشن کرد: استعلام ساده شبا با استعلام تطابق شبا با کد ملی یکی نیست. در استعلام ساده، فقط اعتبار شماره شبا و اطلاعات حساب بررسی می‌شود. در استعلام تطابق، یک لایه اضافه وجود دارد: سیستم بررسی می‌کند که آیا کد ملی داده‌شده واقعاً با صاحب آن حساب تطابق دارد یا نه. این تفاوت در دنیای مبارزه با تقلب مالی، تفاوت بین سیستم ایمن و سیستم آسیب‌پذیر است.

کاربردهای واقعی این سرویس گسترده‌تر از چیزی است که اکثر مدیران محصول در نگاه اول تصور می‌کنند. پرداخت حقوق در سیستم‌های حسابداری، تأیید هویت مالی هنگام ورود کاربر به اپلیکیشن‌های فین‌تک، و احراز هویت حساب در پلتفرم‌های معاملاتی بورس یا ارز دیجیتال سه سناریوی اصلی هستند. هر جایی که پول قرار است از یک نقطه به حساب دیگری برسد، تأیید هویت مالی صاحب آن حساب یک ضرورت است، نه یک گزینه لوکس.

تجربه نشان داده که شرکت‌هایی که این تأیید را نادیده می‌گیرند، معمولاً اولین بار با یک خطای انسانی ساده مواجه می‌شوند: یک رقم اشتباه در شماره شبا که پول را به حساب غلطی هدایت می‌کند. بازیابی آن پول اگر ممکن باشد، ماه‌ها طول می‌کشد.

جهت نمونه پاسخ دریافتی سرویس می‎توانید به صفحه سرویس استعلام شماره شبا نوین وان مراجعه نمایید.

ساختار فنی درخواست و پاسخ API استعلام شبا

درخواست به این سرویس یک پارامتر درخواست API اجباری دارد: شماره شبا. این شماره باید ۲۶ کاراکتر داشته باشد و با حروف IR شروع شود. کلید API هم در هدر درخواست ارسال می‌شود، نه در بدنه.

یک درخواست معتبر این شکل است:

GET /v1/iban/inquiry
Host: apiurl
Authorization: Bearer {YOUR_API_KEY}
Content-Type: application/json

{
  "iban": "IR820540102680020817909007"
}

در صورت موفقیت، پاسخ JSON سرویس چنین ساختاری دارد:

{
  "status": "success",
  "data": {
    "bank": "0121", //شناسه بانک مربوط به شماره حساب
    "bankName": "بانک ملت",
    "status": "Active",
    "statusName": "فعال",
    "depositNumber": "1234567890",
    "bank_name": "بانک ملت",
    "iban" : "IR01212345678912345678",
    "owners": "علی محمدی"
  },
  "request_id": "req_7f3a91bc"
}

وقتی درخواست ناموفق است، ساختار پاسخ تغییر می‌کند. فیلد status مقدار error می‌گیرد و یک فیلد error_code با کد خطای مشخص ظاهر می‌شود. HTTP status codeهای رایج در این سرویس: کد ۲۰۰ یعنی درخواست موفق بوده، کد ۴۰۰ یعنی پارامترهای ورودی معتبر نیستند، کد ۴۰۱ یعنی احراز هویت ناموفق، کد ۴۲۲ معمولاً به معنای شبا نامعتبر یا غیرفعال است، و کد ۴۲۹ یعنی از سقف درخواست‌های مجاز تجاوز کرده‌ای.

برای اطلاعات بیشتر درباره سرویس استعلام شماره شبا کافیست به مقاله مرجع راهنمای جامع استعلام شماره شبا در سامانه نوین وان مراجعه نمایید.

چگونه API استعلام شبا را در پروژه خود فعال و احراز هویت کنید؟

مراحل دریافت کلید API از سامانه نوین وان ساده است اما چند نکته دارد که اگر از اول رعایت نکنی، بعداً دردسرساز می‌شوند. ابتدا در سامانه ثبت‌نام کن و اطلاعات کسب‌وکارت را وارد کن. برای کسب‌وکارهای حقوقی، مدارک ثبت شرکت درخواست می‌شود. بعد از تأیید هویت، یک API Key اختصاصی دریافت می‌کنی که هر بار استفاده‌اش در لاگ‌های سیستم ثبت می‌شود.

روش ارسال توکن در هدر درخواست استاندارد است: مقدار Authorization باید دقیقاً به شکل Bearer {token} باشد، نه فقط token. این اشتباه رایج‌ترین دلیل خطای ۴۰۱ در اولین آزمایش‌هاست. فاصله بین Bearer و توکن فراموش نشود.

پیش از نوشتن هر خطی از کد اصلی، سرویس را با Postman تست کن. یک Collection بساز، متغیرهای محیطی برای API Key و base URL تعریف کن، و با چند شماره شبای واقعی (که از قبل می‌دانی به چه کسی تعلق دارند) تست کن. این کار چند دقیقه وقت می‌برد اما ساعت‌ها debugging بعدی را حذف می‌کند. محیط sandbox سرویس هم در دسترس است که می‌توانی با شماره شباهای آزمایشی کار کنی بدون اینکه هزینه‌ای کسر شود.

یک نکته که خیلی‌ها نادیده می‌گیرند: API Key تست و API Key محیط production باید جدا باشند. هرگز با کلید production در مرحله توسعه کار نکن.

استعلام تطابق شبا با کد ملی: چه زمانی به این سطح از تأیید نیاز دارید؟

صادقانه بگویم: اکثر کسب‌وکارها دیرتر از موعد به این سوال می‌رسند. وقتی اولین مورد تقلب اتفاق می‌افتد. یک حالت رایج در سیستم‌های پرداخت فریلنسری این است که کاربر شماره شبای شخص دیگری را ثبت می‌کند، که شاید عمداً یا سهواً باشد. استعلام ساده شبا این خطا را نمی‌گیرد، چون شبا واقعی و فعال است. اما استعلام تطابق شبا با کد ملی فوری متوجه می‌شود که این دو با هم تطابق ندارند.

از نظر الزامات قانونی، کسب‌وکارهایی که در حوزه خدمات پرداخت، تسهیلات دیجیتال یا سرمایه‌گذاری فعالیت می‌کنند، ملزم به رعایت ضوابط مبارزه با پولشویی هستند. این ضوابط صریحاً تأیید هویت صاحب حساب را الزامی می‌کند، نه فقط اعتبار شماره حساب. استعلام ساده برای این الزام کافی نیست.

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

ارتباط API استعلام شبا با سایر سرویس‌های تأیید هویت مالی

هیچ API تنها نمی‌ایستد. این وب سرویس استعلام بخشی از یک اکوسیستم است و باید در کنار سرویس‌های دیگر دیده شود تا منطق پیاده‌سازی درست باشد.

ترکیب API استعلام شبا با API استعلام شماره کارت یک لایه تأیید دوگانه می‌سازد. فرض کن کاربری هم شماره کارت هم شماره شبا وارد می‌کند. می‌توانی بررسی کنی که آیا هر دو به یک نام تعلق دارند یا نه. این بررسی متقاطع تقلب را سخت‌تر می‌کند، چون جعل همزمان دو اطلاعات مرتبط به هم بسیار دشوارتر است.

در جریان‌های احراز هویت پیچیده‌تر، منطق دو لایه‌ای کارآمدتر است. لایه اول: API استعلام کد ملی که اعتبار هویت ملی کاربر را تأیید می‌کند. لایه دوم: API استعلام شبا که بررسی می‌کند آیا حساب بانکی اعلام‌شده واقعاً به همین هویت تعلق دارد. این ترتیب از نظر هزینه‌ای هم بهینه است، چون اگر لایه اول رد شود، لایه دوم اصلاً فراخوانی نمی‌شود.

API استعلام چک هم یک سرویس مکمل است که معمولاً در سیستم‌های B2B کاربرد دارد. وقتی یک سند تجاری مثل چک دریافت می‌کنی و می‌خواهی قبل از پذیرش، اعتبار آن را تأیید کنی، این سرویس وارد کار می‌شود. ترکیب استعلام شبا و استعلام چک در سیستم‌های خرید-فروش اعتباری یک چارچوب تأیید قوی می‌سازد.

مدیریت خطا، محدودیت نرخ و بهترین شیوه‌های پیاده‌سازی

کدهای خطا را جدی بگیر. خطای «شبا نامعتبر» معمولاً یعنی فرمت ورودی اشتباه است، نه لزوماً اینکه حساب وجود ندارد. قبل از ارسال درخواست، فرمت شبا را validate کن: ۲۶ کاراکتر، شروع با IR، و رقم کنترلی معتبر. این یک چک client-side ساده است که می‌تواند بخش قابل توجهی از درخواست‌های ناموفق را از همان ابتدا فیلتر کند. خطای «حساب غیرفعال» اما نشان‌دهنده وضعیت واقعی حساب است و باید به کاربر منعکس شود.

برای retry logic، یک استراتژی exponential backoff پیاده‌سازی کن. اولین retry بعد از ۱ ثانیه، دومی بعد از ۲ ثانیه، سومی بعد از ۴ ثانیه. اما توجه داشته باش که برای خطاهای ۴۰۰ و ۴۲۲ نباید retry کنی، چون مشکل در داده ورودی است و retry کردن نتیجه را عوض نمی‌کند. فقط برای خطاهای موقت سمت سرور (۵۰۰ و ۵۰۳) و timeout منطقی است.

Caching هم ابزاری است که اگر درست استفاده شود، هم هزینه را پایین می‌آورد هم سرعت پاسخ را بالا می‌برد. اطلاعات یک شبا که یک بار با موفقیت استعلام شده، معمولاً در کوتاه‌مدت تغییر نمی‌کند. می‌توانی نتیجه را با TTL معقولی (مثلاً چند ساعت) cache کنی. البته این قانون برای وضعیت فعال/غیرفعال حساب ممکن است مناسب نباشد، پس با دقت انتخاب کن که کدام فیلدها cache شوند.

امنیت API Key را هرگز دست کم نگیر. کلید API باید فقط در سمت سرور باشد. هرگز در کد frontend، در repository عمومی، یا در environment variable که client-side قابل دسترس است قرار نگیرد. از secrets management مثل Vault یا حتی environment variable‌های سمت سرور استفاده کن. اگر API Key به اشتباه فاش شد، فوری آن را revoke و جایگزین کن.

مقایسه سرویس‌های API استعلام شبا در بازار ایران: چه معیارهایی مهم‌اند؟

بازار ارائه‌دهندگان این سرویس در ایران شلوغ‌تر از آن است که به نظر می‌رسد. اما همه یکسان نیستند. اولین معیار پوشش بانک‌هاست. سرویس‌دهنده‌ای که همه بانک‌های دارای مجوز بانک مرکزی را پوشش ندهد، در یک پیاده‌سازی واقعی دردسرساز می‌شود. حتماً قبل از خرید، لیست دقیق بانک‌های پشتیبانی‌شده را درخواست کن.

نرخ دقت پاسخ و SLA تضمین‌شده دو معیار بعدی هستند. سرویسی که uptime 99.9% ندارد، نمی‌تواند در یک سیستم production مالی استفاده شود. این عدد باید در قرارداد سرویس مکتوب باشد، نه فقط در صفحه بازاریابی. اگر ارائه‌دهنده SLA مکتوب نمی‌دهد، این خودش یک پرچم قرمز است.

مستندات API و محیط sandbox دو چیزی هستند که ارائه‌دهندگان ضعیف معمولاً در آن‌ها کوتاهی می‌کنند. مستندات ناقص یعنی ساعت‌ها وقت تیم توسعه برای آزمون و خطا. sandbox آزمایشی هم برای اینکه بتوانی قبل از تعهد مالی، سرویس را واقعاً تست کنی ضروری است. نوین وان هر دو را فراهم می‌کند.

اما مهم‌ترین معیار که اکثر تیم‌های فنی دیر به آن توجه می‌کنند، اعتبار قانونی ارائه‌دهنده است. ارائه‌دهنده‌ای که مجوزهای لازم از بانک مرکزی را ندارد، در آینده ممکن است با محدودیت‌های قانونی روبرو شود. این مسئله مستقیماً سیستم تو را متأثر می‌کند. قبل از هر تصمیمی، وضعیت مجوز ارائه‌دهنده را بررسی کن.

اگر به دنبال یک سرویس بانکی دیجیتال معتبر برای پیاده‌سازی این قابلیت هستی، سامانه نوین وان با پوشش کامل بانک‌ها، مستندات فنی دقیق و پشتیبانی واقعی، نقطه شروع مناسبی است. می‌توانی از همین امروز با ثبت‌نام در نوین وان، API Key دریافت کنی و با محیط sandbox تست را شروع کنی.

سوالات متداول