تبدیل دسته‌جمعی شماره حساب به شبا برای حقوق و تسویه، بدون هزینهٔ تکراری

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

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

تبدیل را به لحظهٔ ثبت حساب ببرید، نه لحظهٔ واریز

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

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

• شبای برگشتی
• بانک و شمارهٔ حسابی که این شبا از آن‌ها آمده
• زمان تبدیل

وقتی زمان واریز رسید، تسویه فقط خواندن یک ستون پایگاه داده است و هیچ فراخوانی بیرونی در مسیر بحرانی نیست.

کلید کش: بانک و حساب با هم

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

تمیزکردن یعنی ارقام لاتین و حذف خط تیره، نقطه و فاصله. اگر این کار را نکنید، 123-456 و 123456 دو کلید می‌شوند و کش بی‌اثر.

ورودی نامعتبر هزینه ندارد، پس پیش از ارسال دست‌کم فیلتر کنید

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

چند فیلتر محلی و رایگان پیش از دستهٔ اصلی:

• حذف ردیف‌هایی که فقط ارقام کمتر از چهار رقم دارند (فیلد حساب آن‌ها را اصلاً نمی‌پذیرد).
• تشخیص شماره‌هایی که با IR شروع می‌شوند: این‌ها از قبل شبا هستند، تبدیل نمی‌خواهند.
• تشخیص ردیف‌هایی که بانکشان خالی است.

این فیلتر را قبل از صف بگذارید و ردیف‌های ردشده را در گزارش جدا برگردانید تا مسئول مالی بداند کدام ردیف‌ها باید اصلاح شوند.

سه دستهٔ نتیجه، سه رفتار

بعد از اجرا، هر ردیف در یکی از سه وضعیت است و رفتار شما برای هرکدام فرق می‌کند.

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

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

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

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

هماهنگی با تطابق نام

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

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

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

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

یک چرخهٔ نمونه، از ثبت تا واریز

فرض کنید پیمانکاری در ماه اول حسابش را ثبت می‌کند. جریان درست این است:

1. فرم، ورودی را تمیز می‌کند و سرویس تبدیل حساب به شبا را فرا می‌خوانَد.
2. نتیجه با کلید بانک و حساب در جدول ذخیره می‌شود.
3. هر ماه، سامانهٔ حقوق فقط جدول را می‌خواند و دستور پایا می‌سازد.
4. اگر پیمانکار حسابش را عوض کند، کلید تازه ساخته می‌شود و یک تبدیل جدید انجام می‌شود؛ ردیف قبلی دست‌نخورده می‌ماند تا در تاریخچه بتوانید ببینید چه چیزی پرداخت شده.

این جریان در ماه دوم و سوم هیچ فراخوانی به سرویس ندارد. هزینه متناسب با تعداد حساب‌های جدید است، نه تعداد واریزها. این همان فرق «بپرس و نگه دار» با «هر بار بپرس» است.

پایگاه داده چه شکلی داشته باشد

یک جدول کوچک کافی است:

• bank و account_normalized: کلید ترکیبی.
• iban: نتیجه.
• status: موفق یا نتیجهٔ منفی قطعی (مثل حساب غیرفعال).
• checked_at: زمان آخرین تبدیل.

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

ورودی‌های تکراری در یک فایل بزرگ

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

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

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