استعلام‌های بانکی و هویتی ایران

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

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

نوشته‌شده توسط تیم فنی ابرک — بر پایهٔ سرویس‌های بانکداری باز ایران و مدل‌های بومی اودو ۱۹.

مسئله: داده‌ای که باید تأیید شود، دستی وارد می‌شود

سه جای مشخص در چرخهٔ مالی هست که ورودی دستی، ریسک واقعی می‌سازد:

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

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

نه سرویس، روی فیلدهای بومی

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

حالت سندباکس: کار کردن پیش از داشتن کلید

گرفتن کلید واقعی از یک ارائه‌دهندهٔ بانکداری باز فرایند اداری دارد: قرارداد، احراز هویت کسب‌وکار، تعیین تعرفه. اگر نرم‌افزار تا آن روز بلااستفاده بماند، عملاً هیچ‌وقت راه‌اندازی نمی‌شود.

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

• هیچ درخواستی به بیرون فرستاده نمی‌شود. نه اینترنتی لازم است، نه هزینه‌ای می‌دهید.
• پاسخ‌ها قطعی هستند: یک ورودی مشخص همیشه همان خروجی را می‌دهد. یعنی می‌توانید سناریو بسازید، به تیم آموزش بدهید و تست خودکار بنویسید.
• هر پاسخ فیلد sandbox: true دارد و نام‌های برگشتی آشکارا آزمایشی‌اند («آزمایشی سندباکسی»)، تا کسی دادهٔ ساختگی را با واقعی اشتباه نگیرد.
• وضعیت چک صیادی عمداً متنوع تولید می‌شود — گاهی سالم، گاهی برگشتی — تا هر دو مسیر کاری‌تان قابل تمرین باشد.

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

چرا «چارچوب» و نه ارائه‌دهندهٔ سفت‌شده در کد

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

بنابراین همه‌چیز داده است، نه کد:

• نشانی پایه برای سندباکس و عملیاتی، جدا
• مسیر هر سرویس با متغیر: /facility/v2/clients/{client_id}/cardToIban
• نگاشت پارامتر: کدام ورودی ما به کدام پارامتر سرویس می‌رود
• نگاشت پاسخ: مسیر نقطه‌ای مقدار در پاسخ، مثلاً result.depositOwners.0.firstName
• نوع احراز هویت: توکن ثابت، Basic، کلید در سربرگ، یا OAuth2 Client Credentials

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

دو کنترل پیش از هر تماس

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

• الگوریتم Luhn روی شمارهٔ کارت ۱۶ رقمی — همان استاندارد ISO/IEC 7812 که همهٔ کارت‌های بانکی دنیا از آن پیروی می‌کنند. یک رقم جابه‌جا شده همین‌جا گرفته می‌شود.
• کنترل mod-97 روی شبای ۲۶ کاراکتری — طبق ISO 13616، همان استانداردی که بانک مرکزی جمهوری اسلامی ایران برای شبا به‌کار می‌گیرد.

هر دو خطا پیام فارسی روشن می‌دهند، نه یک خطای فنی مبهم.

سابقهٔ استعلام: هم برای حسابرسی، هم برای هزینه

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

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

حریم خصوصی: شمارهٔ کارت و کد ملی در سابقه ماسک می‌شوند (603799******9993). رکورد ممیزی نباید خودش به یک منبع افشای اطلاعات تبدیل شود.

آموزش گام‌به‌گام

1. فعال‌سازی: اپ «استعلام‌های بانکی و هویتی ایران» را از پنل ابرک به اشتراکتان اضافه کنید. پیش‌نیازش حسابداری ایران است.
2. دیدن ارائه‌دهنده‌ها: مسیر حسابداری ← پیکربندی ← استعلام‌های ایران ← ارائه‌دهندگان استعلام. سه ارائه‌دهنده را می‌بینید که همگی برچسب نارنجی «سندباکس» دارند.
3. تمرین بدون کلید: یک طرف حساب باز کنید، در تب حساب‌های بانکی یک حساب بسازید، شمارهٔ کارت ۱۶ رقمی وارد کنید و دکمهٔ «کارت ← شبا» را بزنید. شبا و نام دارنده پر می‌شود. این داده ساختگی است ولی چرخه دقیقاً همان است.
4. استعلام چک: روی فرم چک، شناسهٔ صیاد ۱۶ رقمی را وارد و «استعلام صیاد (سامانه)» را بزنید. وضعیت، مبلغ اعلامی و نام دارنده ثبت می‌شود و اگر مبلغ اعلامی با مبلغی که وارد کرده‌اید نخواند، هشدار در گفتگوی همان چک می‌آید.
5. رفتن به حالت عملیاتی: ارائه‌دهنده را باز کنید، clientId و توکن را وارد کنید، مسیر هر سرویس را با داکیومنت روز تطبیق دهید، و نوار وضعیت را روی «عملیاتی» بگذارید.
6. کنترل هزینه: در سابقهٔ استعلام، فیلتر «عملیاتی» را بزنید و ستون هزینه را جمع بگیرید.

چه چیزی این افزونه نیست

این افزونه ارائه‌دهندهٔ سرویس استعلام نیست و کلید نمی‌فروشد. قرارداد و تعرفه را مستقیماً با فینوتک، جیبیت، زیبال یا هر ارائه‌دهندهٔ دیگری می‌بندید؛ این افزونه فقط کاری می‌کند که آن سرویس داخل نرم‌افزارتان قابل استفاده باشد و ردش بماند.

شروع کنید

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