چرا تطابق شماره حساب با کد ملی بانک می‌خواهد و قالب حساب مهم است

شماره حساب به‌تنهایی هیچ‌چیز را مشخص نمی‌کند؛ باید بدانید مال کدام بانک است. به همین دلیل تطابق کد ملی و شماره حساب چهار ورودی دارد و «بانک» یکی از آن‌هاست، چیزی که در تطابق کارت و شبا اصلاً لازم نیست.

اگر پاسخ منفی گرفته‌اید در حالی که مطمئنید حساب مال همان فرد است، احتمالاً یکی از دو ورودی ویژهٔ این سرویس را درست نفرستاده‌اید: بانک یا قالب شماره حساب. این نوشته دربارهٔ همین دو است.

چرا بانک لازم است

شماره کارت شانزده رقم است و ششِ اولش بانک را نشان می‌دهد. شبا بیست‌وچهار رقم دارد و سه رقم بانک در آن هست. شماره حساب این‌ها را ندارد. هر بانک شماره حساب را با قالب خودش می‌سازد، طول و جداکننده‌اش فرق می‌کند، و به نظر من نباید فرض کنید شماره‌ای در همهٔ بانک‌ها یکتاست. بدون نام بانک، یک عدد معنایی ندارد.

برای همین فرم شما باید از کاربر بپرسد «حساب در کدام بانک است؟» و پاسخ را از یک فهرست بسته بگیرد، نه متن آزاد.

بانک چطور فرستاده می‌شود

مقدار فیلد bank شناسهٔ لاتین بانک است، مثل mellat. کد سه‌رقمی بانک (همان که در شبا هست، مثلاً 012) هم پذیرفته می‌شود. فهرست بانک‌ها در مستندات API در جدول «کد بانک‌ها» آمده است.

اشتباه رایج: نام فارسی بانک را در رشته بفرستید («بانک ملت»). سرویس انتظار شناسه دارد و نام فارسی از اعتبارسنجی نمی‌گذرد. پاسخ آن invalid_input است، رایگان است، ولی کاربر دوباره منتظر می‌ماند.

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

قالب شماره حساب را دست نزنید

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

نتیجه برای فرم شما:

• فیلد را رشتهٔ متنی بگیرید، نه عددی. اگر type="number" بگذارید، صفرهای ابتدایی از بین می‌روند و خط تیره پذیرفته نمی‌شود.
• ارقام فارسی را قبول کنید و لاتین کنید.
• هر چیزی که رقم، -، / یا . نیست را بردارید، ولی این سه را نه.
• از کاربر بخواهید دقیقاً همان‌طور بنویسد که در برنامه یا رسید بانک دیده است.

حداقل چهار رقم لازم است، وگرنه فرم رد می‌شود.

یک راه دیگر: اول به شبا تبدیل کنید

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

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

چک‌لیست پیش از ارسال

پیش از اینکه دکمه را بزنید، فرم شما باید این پنج چیز را تأیید کرده باشد. همه رایگان‌اند چون پیش از API انجام می‌شوند.

1. کد ملی ده رقمی با رقم کنترل معتبر.
2. تاریخ تولد شمسی، هشت رقم، با روزی که در آن ماه وجود دارد.
3. بانک از فهرست بسته انتخاب شده.
4. شماره حساب رشتهٔ متنی است و دست‌کم چهار رقم دارد.
5. کاربر می‌داند حساب باید به نام خودش باشد.

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

یک سناریوی فرضی

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

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

بانک را از روی شماره حدس نزنید

وسوسه می‌شود برای کم‌کردن فیلد، بانک را خودکار تشخیص دهید. از شماره کارت می‌شود، چون ششِ اول بانک را نشان می‌دهد (راهنمای تشخیص بانک از روی شماره کارت را ببینید). از شبا هم می‌شود، چون سه رقم بانک دارد. از شماره حساب نه، چون قالب آن در بانک‌ها یکسان نیست. اگر کاربر هم شماره حساب را می‌دهد، هم کارت یا شبا را، از دومی بانک را بگیرید؛ وگرنه صریح بپرسید.

نمونه درخواست

bash curl -X POST 'https://example.com/api/v1/account-national-id-match/' \ -H 'Authorization: Bearer melli_live_…' \ -H 'Content-Type: application/json' \ -d '{"nationalCode":"0013542419","birthDate":"1370/01/05","bank":"mellat","bankAccount":"0123456789"}'

اعداد نمونه ساختگی‌اند.

وقتی پاسخ منفی است

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

تاریخ تولد شمسی است (نه میلادی) و کامل. سه قالب 1370/01/05، 1370-01-05 و 13700105 پذیرفته می‌شوند.

آنچه این سرویس نمی‌کند

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

نکتهٔ آخر

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