API و وب سرویس تبدیل حساب به شبا
شمارهٔ شبای یک حساب بانکی را از روی شمارهٔ حساب و بانک برمی‌گرداند، برای فایل‌ها و نرم‌افزارهایی که هنوز شمارهٔ حساب دارند.
این سرویس چه می‌کند
این وب سرویس دو ورودی میگیرد، شمارهٔ حساب در bankAccount و بانک در bank، و یک مقدار برمی‌گرداند: شبا در فیلد IBAN. نام صاحب حساب برنمی‌گردد.
موقعیت معمول آن مهاجرت داده است. نرم‌افزار حسابداری یا فایل اکسل قدیمی فقط شمارهٔ حساب تأمین‌کننده‌ها و کارکنان را دارد، ولی ماژول پرداخت جدید فقط شبا میپذیرد. یک بار تبدیل دسته‌ای، این شکاف را می‌بندد.
چرا بانک هم باید گفته شود
قالب شمارهٔ حساب بین بانکها یکسان نیست و همان رشتهٔ رقمی در دو بانک می‌تواند دو حساب متفاوت باشد. به همین دلیل فیلد bank اجباری است و باید شناسهٔ لاتین بانک باشد، مثل mellat. فهرست شناسه‌ها در مستندات API هست و بانک اشتباه، استعلامی واقعی با نتیجهٔ بی‌ربط می‌سازد.
شمارهٔ حساب را همانطور که بانک نوشته بفرستید
بعضی بانکها در شمارهٔ حساب خط تیره، اسلش یا نقطه می‌گذارند. این نویسه‌ها را پاک نکنید: فیلد bankAccount رقم، خط تیره، اسلش و نقطه را میپذیرد و حداقل چهار رقم می‌خواهد. بعد از تبدیل شبا را در ستون جدا و شمارهٔ حساب را به‌صورت رشته ذخیره کنید، نه عدد، تا صفرهای ابتدایی نیفتد.
حساب غیرفعال با حسابِ نادرست یکی نیست
نمونهٔ مستند این سرویس وضعیت «حساب غیرفعال» را با کد ACCOUNT_NOT_ACTIVE نشان میدهد. در درگاه ما این وضعیت به پاسخ not_found با HTTP ۲۰۰ تبدیل میشود و هزینه دارد. در گزارش مهاجرت این ردیف‌ها را جدا از «شمارهٔ حساب غلط تایپ شده» علامت بزنید، چون اولی نیاز به تماس با فرد و دومی نیاز به اصلاح داده دارد.
بعد از تبدیل، نام را از کجا بیاوریم
اگر باید مطمئن شوید شبا به نام فرد موردنظر است، خروجی IBAN را به سرویس استعلام شبا بدهید. زنجیرهٔ «حساب به شبا، بعد استعلام شبا» دو فراخوان است و در عوض هم شبا و هم نام صاحب حساب دارید.
آنچه این سرویس نمی‌کند
نام صاحب حساب را برنمی‌گرداند و موجودی نمی‌دهد. وجود حساب با مالکیت مشخص را هم تضمین نمی‌کند: فقط شبای متناظر با آن شماره و بانک را میدهد. شمارهٔ کارت را هم نمی‌پذیرد؛ برای کارت، سرویس تبدیل کارت به شبا را استفاده کنید.
کجا به کار می‌آید
- مهاجرت از نرم‌افزار حسابداری قدیمیفهرست حساب تأمین‌کننده‌ها که فقط شمارهٔ حساب دارد، پیش از انتقال به ماژول پرداخت جدید به شبا تبدیل میشود و ردیف‌های ناموفق برای اصلاح جدا می‌ماند.
- فایل حقوق مؤسسه‌های آموزشیآموزشگاه شمارهٔ حساب معلم‌های حق‌التدریس را از قراردادهای کاغذی وارد کرده و برای فایل واریز دسته‌جمعی هر ماه به شبا نیاز دارد.
- ثبت حساب بازنشستگان در صندوق‌های داخلیصندوق کارکنان یک شرکت، حساب‌های ثبت‌شده در دفترچه‌های قدیمی را به شبا تبدیل می‌کند تا پرداخت‌های دوره‌ای بدون بازنویسی دستی انجام شود.
ورودی و خروجی
ورودی
bankAccountstringشمارهٔ حسابشماره حساب دقیقاً با همان قالبی که بانک داده؛ اگر خط تیره، اسلش یا نقطه دارد، همانطور بفرستید.bankstringبانکشناسهٔ لاتین بانک از جدول «کد بانکها»، مثل mellat. کد سه‌رقمی بانک در شبا (مثل 012) هم پذیرفته میشود.جدول کد بانکها در مستنداتخروجی
IBANstringIR700620000000XXX295898001قیمت و شرط پرداخت
قیمت هر فراخوان API تبدیل حساب به شبا ۸۰۰ تومان است.
| تعداد استعلام در ماه | قیمت هر فراخوان |
|---|---|
| همهٔ فراخوان‌ها | ۸۰۰ تومان |
آخرین تغییر قیمت:
مبلغ پیش از تماس با سرویس مرجع از موجودی پنل قفل میشود و اگر پاسخی نیاید، آزاد میشود. ورودی نامعتبر، در دسترس نبودن سرویس مرجع و عبور از سقف نرخ هزینه‌ای ندارند. «رکوردی یافت نشد» یک پاسخ معتبر است و هزینه دارد.
کمترین مبلغ شارژ پنل: ۵۰۰٬۰۰۰ تومان
پرسش‌های متداول
تبدیل شماره حساب به شبا چه ورودی‌هایی می‌خواهد؟
دو ورودی: شمارهٔ حساب در bankAccount و شناسهٔ لاتین بانک در bank. کارت یا کد ملی لازم نیست.
چرا برای تبدیل حساب به شبا باید بانک را هم بگویم؟
چون قالب شمارهٔ حساب در بانکها یکسان نیست و یک رشتهٔ رقمی ممکن است در دو بانک دو حساب باشد. بانک اشتباه، شبای یک حساب دیگر یا نتیجهٔ یافتنشده میدهد.
شماره حساب را با خط تیره بفرستم یا بدون آن؟
همانطور که بانک نوشته بفرستید. فیلد رقم، خط تیره، اسلش و نقطه را میپذیرد و حداقل چهار رقم لازم دارد. شمارهٔ حساب را در پایگاه داده رشته ذخیره کنید.
آیا همهٔ بانکها تبدیل حساب به شبا را پشتیبانی میکنند؟
بانکهای فهرستشده در مستندات API قابل انتخاباند. اگر نتیجهای نبود، پاسخ not_found میگیرید. برای بانکی که جواب ندهد، گرفتن شبا از خود کاربر را در سامانهتان نگه دارید.
اگر حساب غیرفعال باشد چه پاسخی می‌گیرم؟
پاسخ not_found با HTTP ۲۰۰ و ok:false، و پیام سرویس مرجع غیرفعال‌بودن حساب را می‌گوید. این پاسخ هزینه دارد و با حسابِ تایپ‌شدهٔ اشتباه فرق دارد.
این سرویس نام صاحب حساب را هم میدهد؟
خیر. فقط شبا (IBAN) برمیگردد. برای نام، شبای برگشتی را به سرویس استعلام شبا بدهید.
اگر شمارهٔ حساب خیلی کوتاه باشد هزینه کسر میشود؟
خیر. شمارهای با کمتر از چهار رقم یا بانک ناشناخته پیش از تماس با سرویس مرجع پاسخ invalid_input با HTTP ۴۰۰ میگیرد، بدون کسر هزینه.
برای تبدیل فهرست بزرگ چه نکتهای مهم است؟
حد نرخ را رعایت کنید: پیشفرض ۶۰ فراخوان در دقیقه برای هر سرویس است و پاسخ ۴۲۹ رایگان است. شبای برگشتی را ذخیره کنید تا در دورهٔ بعد دوباره فراخوان نشود.