خروجی استعلام شبا: is_transferable یعنی چه و چه چیزی را تأیید نمی‌کند؟

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

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

سه نتیجهٔ ممکن

وقتی شبا را می‌فرستید، یکی از این سه اتفاق می‌افتد:

۱. موفق. data پر است: نام، بانک و پرچم انتقال‌پذیری.

۲. شبا معتبر نیست. سرویس مرجع کد IBAN_NOT_VALID را با پیام «شماره شبای وارد شده معتبر نیست» می‌دهد و data خالی است. در API ما، ساختار شبا پیش از ارسال بررسی می‌شود و اگر ناسازگار باشد، پاسخ invalid_input می‌گیرید و هزینه‌ای کسر نمی‌شود. تفصیلش در راهنمای خطای شبای نامعتبر آمده.

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

تفاوت ۲ و ۳ برای کاربرتان یکی است («شبا را دوباره بررسی کنید»)، ولی برای حسابداری شما یکی هزینه دارد و دیگری نه. پیام یکسان را به کاربر نشان دهید، رفتار متفاوت را در لاگ.

is_transferable یعنی چه، و چه نیست

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

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

به‌نظر من بزرگ‌ترین خطر این است که تیم محصول پرچم سبز را «تأیید حساب» بنامد و پیام «حساب شما تأیید شد» نشان دهد. تأیید نیست؛ یک پیش‌بررسی است.

نام صاحب حساب: داده خام، نه برچسب آماده

نام همان چیزی است که در شبکهٔ بانکی ثبت شده و ممکن است ناهمگون باشد. در نمونهٔ مستندات، نام یک موسسه با نیم‌فاصله‌های پراکنده و فاصله‌های اضافه برگشته است («خیریه‌ تو‌انبخشی‌ …»). یعنی در عمل ممکن است ی/ک عربی، نیم‌فاصلهٔ اضافی، فاصلهٔ دوبل یا نام کامل شرکت بیاید. اگر نام را عیناً با نام ثبت‌شدهٔ کاربر مقایسه کنید، درست‌ها را هم رد می‌کنید. راه‌حلش در مقالهٔ مقایسهٔ نام آمده.

نمایش نام به کاربر، بی‌نیاز از این مقایسه است و بهترین کار ممکن: «حساب به نام فلانی است، درست است؟».

نمونهٔ پاسخ

json { "ok": true, "service": "iban-inquiry", "data": { "name": "…", "bank_name": "…", "is_transferable": true }, "source": { "cached": false, "stale": false } }

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

یک نکته دربارهٔ کش

نگاشت شبا به صاحب حساب کند تغییر می‌کند. پس ممکن است پاسخی که دریافت می‌کنید از کش بیاید، و اگر سرویس مرجع در دسترس نباشد، آخرین پاسخ معتبر با برچسب stale برگردد. برای واریزی بزرگ که همین دم انجام می‌شود، به source.fetchedAt نگاه کنید و اگر قدیمی بود، دوباره استعلام بگیرید.

چند پرسش رایج در پیاده‌سازی

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

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

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

کجای جریان پرداخت بگذاریم

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

نمونه‌ای از منطق تصمیم

js if (!out.ok) return showFixIbanMessage(out.error.code); const { name, bank_name, is_transferable } = out.data; if (!is_transferable) return askAnotherAccount(); return confirmWithUser({ name, bank_name });

شاخه‌ها ساده‌اند ولی ترتیبشان مهم است: اول ok، بعد پرچم، بعد تأیید کاربر. و در لاگ داخلی، علت شاخهٔ اول را (ورودی نامعتبر یا یافت‌نشدن) جدا ثبت کنید.

تفاوت با تبدیل کارت و حساب

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

نکتهٔ حسابداری برای تیم مالی

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

آنچه این استعلام نمی‌کند

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

پیشنهاد من

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

نمونهٔ درخواست و فیلدهای وب‌سرویس استعلام شبا در صفحهٔ خودش هست.