نتیجه‌های تطابق کد ملی و شبا: شبا نامعتبر یا تطابق ندارد؟

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

این نوشته نتیجه‌های ممکن تطابق کد ملی و شبا را کنار هم می‌گذارد و برای هر کدام می‌گوید چه چیزی را به کاربر بگویید.

چهار نتیجه

۱. تطابق دارد (matched: true). شبا با این کد ملی و تاریخ تولد می‌خواند. هزینه دارد.

۲. تطابق ندارد (matched: false). پرسش انجام شد، جواب منفی است. هزینه دارد.

۳. شبا نامعتبر. سرویس مرجع، شبا را قابل پذیرش نمی‌داند. این پاسخ در API ما به‌صورت خطای ورودی طبقه‌بندی می‌شود و هزینه‌ای کسر نمی‌شود.

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

دو نتیجهٔ اول «پرسش انجام شد» هستند. دو نتیجهٔ آخر «پرسش درست نبود».

چیزی که در نمونه‌های مستندات مرجع جالب است

در نمونه‌های مستندات سرویس مرجع، دو حالت مختلف، یعنی «شبا نامعتبر» و «شبا پیدا نشد»، هر دو با یک کد برمی‌گردند: IBAN_NOT_VALID. یعنی شبایی که ساختارش درست است ولی در سیستم بانکی وجود ندارد هم می‌تواند همین کد را بگیرد.

نتیجهٔ عملی: «شبا نامعتبر» لزوماً به معنای «رقمی را غلط تایپ کرده‌اید» نیست. ممکن است شبا درست‌نوشته باشد و حسابی پشتش نباشد. پیام شما نباید ادعای بیش از آنچه می‌دانید بکند.

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

اینکه کدام دقیقاً چه رفتاری در تعامل واقعی دارد را من از بیرون نمی‌توانم تضمین کنم؛ این بر پایهٔ نمونه‌های مستندات است. اگر برایتان مهم است، با چند شبای خودتان بیازمایید.

هزینه: چرا فرق می‌کند

جدول زیر منطق صورتحساب را جمع می‌کند.

قاعدهٔ کلی در API: جوابی که قابل استفاده باشد هزینه دارد، حتی اگر جواب «نه» باشد. مستندات API فهرست کدها و ستون هزینه را دارد. به آن تکیه کنید و حدس نزنید.

برای تیم مالی شما این یعنی: نسبت پاسخ‌های منفی به کل، مستقیم روی هزینه اثر می‌گذارد. اگر فرم شما کاربران را زیاد به شبای اشتباه یا کد ملی اشتباه می‌کشاند، بخشی از پول صرف پاسخ‌های منفی می‌شود. کاهش آن‌ها بیشتر کار فرم است تا کار API.

تفاوت در پیام به کاربر

برای هر نتیجه یک پیام جدا بنویسید.

• موفق: «حساب تأیید شد.» بدون جزئیات.
• منفی: «این شبا با اطلاعات هویتی واردشده نخواند. مطمئن شوید حساب به نام خودتان است و تاریخ تولد را درست وارد کرده‌اید.»
• شبا نامعتبر: «شماره شبا پذیرفته نشد. دوباره از روی برنامهٔ بانک بخوانید.»
• خطای فرم: پیام خود فیلد، همان لحظه.

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

حساب شرکتی

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

در کد، چطور جدا کنید

این اسکلت چهار نتیجه را از هم جدا می‌کند. ساختار data را از پاسخ نمونهٔ صفحهٔ سرویس بگیرید.

js function classify(body) { if (body.ok && body.data?.matched === true) return 'verified'; if (body.ok && body.data?.matched === false) return 'mismatch'; switch (body.error?.code) { case 'invalid_input': return 'bad-input'; // فرم یا شبا؛ رایگان case 'temporarily_unavailable': return 'retry-later'; // رایگان default: return 'unknown'; } }

نام دقیق کدهای خطا را در مستندات API ببینید و نمونهٔ بالا را فقط الگو بدانید. نکتهٔ اصلی این است که unknown را هم یک شاخه بدانید: کدی که فردا اضافه شود نباید ثبت‌نام را بشکند.

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

تصور کنید یک پلتفرم تسویه به فروشندگان، شبا را هنگام ثبت می‌گیرد. فروشنده‌ای شبای خودش را از پیامک بانک کپی می‌کند. در کپی، یک فاصله و کاراکتر نامرئی همراه شده. API فاصله را برمی‌دارد و ادامه می‌دهد. فروشندهٔ دیگری شبای همسرش را وارد می‌کند: پاسخ منفی. سومی شبای شرکتش را می‌دهد: باز منفی.

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

چه چیزی را لاگ بگیرید

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

ساختار شبا، در یک نگاه

شبا با IR شروع می‌شود و دو رقم کنترلی و بیست‌وچهار رقم دارد (مجموعاً ۲۶ نویسه). جایگاه کد بانک در آن ثابت است. اگر شبا را بی‌فاصله و با حروف بزرگ بفرستید، یکدست‌سازی و اعتبارسنجی راحت‌تر است؛ فاصله و حروف کوچک را API خودش یکدست می‌کند. برای ساختار کامل، راهنمای شماره شبا چیست را ببینید.

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

• دلیل پاسخ منفی را نمی‌گوید.
• نام صاحب حساب را برنمی‌گرداند.
• وضعیت حساب (فعال، مسدود) را نمی‌سنجد.
• شبایی که ساختار ندارد را نمی‌شود با آن «اصلاح» کرد؛ باید دوباره از کاربر بگیرید.

اگر عجله دارید

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