API و وب سرویس استعلام شماره شبا
نام صاحب حساب، نام بانک و امکان واریز را برای یک شمارهٔ شبا برمی‌گرداند، پیش از آنکه دستور پرداخت ثبت شود.
این سرویس چه میکند
این وب سرویس یک شمارهٔ شبا میگیرد و سه مقدار برمی‌گرداند: نام صاحب حساب در فیلد name، نام بانک در bank_name و یک مقدار درست/نادرست در is_transferable که میگوید واریز به آن حساب ممکن است یا نه.
جای طبیعی‌اش لحظهٔ پیش از ثبت دستور پرداخت است، وقتی شبا از یک فرم، فایل اکسل یا قرارداد آمده و کسی آن را با چشم ندیده. واریز دسته‌جمعی با پایا یک خطای تایپی را تا فردا نشان نمی‌دهد؛ استعلام همان خطا را قبل از ثبت نشان می‌دهد.
پیش از فراخوان، آنچه را خودتان رایگان می‌سنجید
شبای معتبر با IR شروع میشود و بعد از آن ۲۴ رقم دارد و باقی‌ماندهٔ تقسیم عدد بازچینی‌شده بر ۹۷ باید ۱ شود. این کنترل ساختاری در سمت شما هزینه‌ای ندارد و بخش بزرگی از خطاهای تایپی را همان‌جا میگیرد.
درگاه ما هم همین کنترل را اجرا میکند و شبای ناسازگار را با invalid_input و بدون کسر هزینه رد میکند. ولی ساختار درست یعنی حساب وجود دارد؟ نه. شبایی که از کنترل گذشته ممکن است به هیچ حسابی وصل نباشد، و این را فقط استعلام میگوید.
وقتی «یافت نشد» برمیگردد
شبای ساختاری‌درستِ بدون حساب پاسخ not_found میگیرد، با HTTP ۲۰۰ و ok:false. این پاسخ معتبر است و هزینه دارد، چون استعلام انجام شده است. در سامانهٔ خود آن را «خطای سیستم» نشان ندهید؛ ردیف پرداخت را نگه دارید و از ثبت‌کننده بخواهید شبا را اصلاح کند.
نام را چطور مقایسه کنید
نام برگشتی همانطور است که در بانک ثبت شده و برای مقایسهٔ ماشینی تمیز نیست. نمونهٔ مستند سرویس مرجع نامی با نیمفاصلهها و فاصلههای اضافه در جاهای عجیب نشان می‌دهد، خصوصاً برای نام مؤسسه‌ها و شرکت‌ها.
پیش از هر مقایسه، یای و کاف عربی را فارسی کنید، نیمفاصله و فاصلههای تکراری را حذف کنید و هر دو طرف را یکدست کنید. برابری کامل را شرط نگذارید؛ بهتر است نام را به کاربر یا حسابدار نشان بدهید تا خودش تأیید کند.
is_transferable برابر نادرست بود
مقدار نادرست یعنی سرویس مرجع واریز به این حساب را ممکن نمی‌داند. دلیل را برنمی‌گرداند، پس دستور پرداخت را متوقف کنید و شبای دیگری بخواهید، به‌جای اینکه دلیلی حدس بزنید.
آنچه این سرویس نمی‌کند
موجودی، سقف واریز و گردش حساب را نمی‌گوید. مالکیت را هم با کد ملی کاربر شما نمی‌سنجد: فقط نام صاحب حساب را نشان می‌دهد. اگر می‌خواهید خود سامانه بگوید نام با فرد موردنظر می‌خواند، سرویس جداگانهٔ تطابق شبا و نام همین کار را میکند.
کجا به کار می‌آید
- ثبت تأمین‌کنندهٔ جدید در دفتر پرداختواحد مالی پیش از افزودن شبای یک تأمین‌کننده به فهرست پرداخت، نام صاحب حساب را با نام روی فاکتور مقایسه میکند و اختلاف را قبل از اولین واریز می‌بیند.
- تسویهٔ دسته‌جمعی پیمانکارانفایل اکسل شباهای پیمانکاران پیش از ساخت فایل پایا ردیف‌به‌ردیف استعلام میشود؛ ردیف‌های یافت‌نشده و غیرقابل‌واریز جدا می‌شوند و بقیه می‌روند.
- پرداخت به مؤسسه‌های خیریهپلتفرم کمک‌های مردمی نام مؤسسهٔ دریافت‌کننده را از روی شبای ثبتشده نشان می‌دهد تا مدیر کمپین پیش از تسویه، حساب مقصد را تأیید کند.
ورودی و خروجی
ورودی
ibanstringشباIR و ۲۴ رقم، بی فاصله.خروجی
bank_namestringآيندهis_transferablebooleannamestringخیریه تو‌انبخشی بچه های آسمان کامرانقیمت و شرط پرداخت
قیمت هر فراخوان API استعلام شماره شبا ۸۰۰ تومان است. با افزایش مصرف ماهانه قیمت کم میشود: از فراخوان شمارهٔ ۱۰۰ تا ۴۹۹ در ماه، هر فراخوان ۷۰۰ تومان؛ از فراخوان شمارهٔ ۵۰۰ تا ۹۹۹ در ماه، هر فراخوان ۵۹۰ تومان؛ از فراخوان شمارهٔ ۱٬۰۰۰ در ماه به بعد، هر فراخوان ۴۵۰ تومان.
| تعداد استعلام در ماه | قیمت هر فراخوان |
|---|---|
| ۱ تا ۹۹ | ۸۰۰ تومان |
| ۱۰۰ تا ۴۹۹ | ۷۰۰ تومان |
| ۵۰۰ تا ۹۹۹ | ۵۹۰ تومان |
| ۱٬۰۰۰ و بیشتر | ۴۵۰ تومان |
شمارش برای هر کسب‌وکار و همین سرویس، از ابتدای هر ماه شمسی دوباره شروع میشود و فقط فراخوان‌هایی که هزینه داشته‌اند شمرده می‌شوند. قیمت هر فراخوان پیش از تماس با سرویس مرجع حساب میشود و همان مبلغی است که کسر میشود.
آخرین تغییر قیمت:
مبلغ پیش از تماس با سرویس مرجع از موجودی پنل قفل میشود و اگر پاسخی نیاید، آزاد میشود. ورودی نامعتبر، در دسترس نبودن سرویس مرجع و عبور از سقف نرخ هزینه‌ای ندارند. «رکوردی یافت نشد» یک پاسخ معتبر است و هزینه دارد.
کمترین مبلغ شارژ پنل: ۵۰۰٬۰۰۰ تومان
پرسش‌های متداول
استعلام شماره شبا دقیقاً چه اطلاعاتی نشان می‌دهد؟
نام صاحب حساب، نام بانک صادرکننده و اینکه واریز به آن حساب ممکن است یا نه. موجودی، سقف واریز و گردش حساب نشان داده نمی‌شود.
با شماره شبا میشود نام صاحب حساب را فهمید؟
بله. نام صاحب حساب در فیلد name برمیگردد، همانطور که در بانک ثبت شده است. برای مقایسهٔ ماشینی، یای و کاف عربی و نیمفاصلهها را پیش از مقایسه یکدست کنید.
برای استعلام شبا رمز کارت یا CVV2 لازم است؟
خیر. ورودی این سرویس فقط فیلد iban است، یعنی IR و ۲۴ رقم. هیچ رمز، CVV2 یا تاریخ انقضایی گرفته نمی‌شود و نباید از کاربر بخواهید.
اگر شبا از نظر ساختار درست باشد، یعنی حساب وجود دارد؟
نه. کنترل ساختاری فقط الگو و رقم کنترلی را میسنجد. شبایی که از آن گذشته ممکن است به هیچ حسابی وصل نباشد و در استعلام پاسخ not_found بگیرد.
شبای نامعتبر هزینه دارد؟
خیر. شبایی که الگو یا رقم کنترلیاش درست نباشد پیش از تماس با سرویس مرجع رد میشود و پاسخ invalid_input با HTTP ۴۰۰ میگیرد، بدون کسر هزینه.
اگر شبا پیدا نشد هزینه کسر میشود؟
بله. «حسابی با این شبا نیست» پاسخ معتبری است که استعلامش انجام شده، پس هزینه دارد. پاسخ با HTTP ۲۰۰ و ok:false و کد not_found برمیگردد.
چطور نام برگشتی را با نام ثبتشده در سامانهام مقایسه کنم؟
هر دو نام را یکدست کنید: یای و کاف عربی را فارسی کنید، نیمفاصله و فاصلههای تکراری را حذف کنید. بعد شباهت را بسنجید و در صورت تردید، نام را به کاربر نشان بدهید.
حد نرخ وب سرویس استعلام شبا چقدر است؟
پیشفرض ۶۰ فراخوان در دقیقه برای هر سرویس است. عبور از آن پاسخ ۴۲۹ با هدر Retry-After میگیرد و هزینه ندارد. برای حجم بیشتر باید سقف حساب شما بالا برده شود.
پاسخ ممکن است از کش بیاید؟
بله. فیلد source.cached مشخص میکند پاسخ از کش آمده یا از سرویس مرجع، و fetchedAt زمان آن را میگوید. اگر سرویس مرجع در دسترس نباشد، آخرین پاسخ معتبر با stale برابر درست برمیگردد.