مستندات فنی API استعلام شماره شبا در نوین وان روی یک endpoint مشخص تعریف شده است: درخواست GET به آدرس https://api.novin.one/v1/ibans با هدر Authorization: Bearer YOUR_ACCESS_TOKEN و پارامتر به‌صورت value=IR5201500000001234567891. در پاسخ موفق، اطلاعات بانک، شماره حساب، وضعیت حساب، نام بانک و فهرست صاحبان حساب برمی‌گردد. همین قرارداد برای تیم‌های بک‌اند و یکپارچه‌سازی مبنای پیاده‌سازی production است و از حدس‌زدن روی ساختار درخواست و پاسخ جلوگیری می‌کند.
این صفحه، جزئیات فنی همان endpoint را برای توسعه‌دهندگان بک‌اند، مهندسان یکپارچه‌سازی و معماران نرم‌افزار در فین‌تک، PSP، پرداخت‌یار و نئوبانک جمع‌بندی می‌کند. اگر هنوز در مرحله انتخاب سرویس یا طراحی معماری هستید، ابتدا مرجع تصمیم‌گیری فنی وب‌سرویس استعلام شماره شبا را ببینید؛ اینجا تمرکز روی قرارداد دقیق فراخوانی، فیلدها، خطاها و اشتباهات رایج پیاده‌سازی است.
آدرس endpoint و روش احراز هویت
سرویس استعلام شماره شبا با دریافت شبا، اطلاعات مرتبط با حساب را به‌صورت لحظه‌ای برمی‌گرداند. خروجی برای تسویه، واریز، احراز هویت بانکی و کاهش خطای مالی استفاده می‌شود؛ بنابراین قرارداد فراخوانی باید در کلاینت ثابت و قابل تست باشد.
آدرس پایه فراخوانی این است:
GET https://api.novin.one/v1/ibans/?value=IR5201500000001234567891ارتباط فقط روی HTTPS انجام می‌شود. احراز هویت از نوع توکن Bearer است؛ یعنی در هر درخواست باید توکن دسترسی معتبر در هدر Authorization ارسال شود. اگر توکن نامعتبر باشد یا حساب کاربری غیرفعال باشد، فراخوانی رد می‌شود.
| پارامتر هدر | مقدار / نوع | توضیح |
|---|---|---|
| Content-Type | application/json | نوع محتوای بدنه درخواست |
| Authorization | Bearer accessToken | توکن دسترسی؛ به‌جای accessToken مقدار واقعی توکن قرار می‌گیرد |
نمونه فراخوانی با curl:
curl --request GET 'https://api.novin.one/v1/ibans/?value=IR5201500000001234567891' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data ''توکن را در کد منبع، مخزن عمومی یا لاگ خام قرار ندهید. مقدار را از متغیر محیطی، مخزن اسرار یا سرویس مدیریت پیکربندی بخوانید و فقط در هدر درخواست تزریق کنید. برای محیط آزمایشی و کنترل مصرف، از مسیرهای Sandbox و گزارش مصرف در پنل استفاده کنید تا قبل از اتصال به ترافیک واقعی، رفتار کلاینت و سقف فراخوانی را بسنجید.
پارامترهای endpoint استعلام شبا و ساختار درخواست
بدنه درخواست یک شیء JSON ساده است. تنها ورودی اجباری، شماره شبا است که با کلید value ارسال می‌شود.
| نام فیلد | نوع | توضیح |
|---|---|---|
| value | string | شماره شبا |
قبل از ارسال، سه کنترل ساده در کلاینت جلوی بسیاری از خطاهای ۴xx را می‌گیرد. اول، خالی نبودن value. دوم، یکدست‌سازی ورودی: حذف فاصله و نویسه اضافی، و اطمینان از پیشوند IR در صورت نیاز کسب‌وکار. سوم، رد زودهنگام ورودی‌هایی که از نظر طول یا الگوی کلی شبا ایران قابل قبول نیستند. این کنترل‌ها جایگزین اعتبارسنجی سرویس نیستند؛ فقط ترافیک بی‌فایده و هزینه خطای تکراری را کم می‌کنند.
اشتباه رایج تیم‌ها این است که شبا را گاهی در query string و گاهی در body می‌فرستند، یا کلید را به نام‌هایی غیر از value تغییر می‌دهند. قرارداد فعلی endpoint استعلام شبا نوین وان برای این مسیر، ارسال JSON در بدنه با همان کلید است. هر انحراف بدون هماهنگی، به خطای بدنه نامعتبر یا شبا الزامی منجر می‌شود.
ساختار پاسخ JSON استعلام شبا و معنی فیلدها
پاسخ موفق یک شیء با وضعیت موفقیت و بخش داده است. نمونه واقعی:
{
"success": true,
"data": {
"bank": "SEPAH",
"depositNumber": "1234568791",
"iban": "IR5201500000001234567891",
"status": "ACTIVE",
"owners": [
{
"firstName": "محمد",
"lastName": "محمدی"
}
],
"bankName": "بانک سپه",
"statusName": "فعال"
}
}فیلدهای داخل data این‌طور خوانده می‌شوند:
| فیلد | نوع | توضیح |
|---|---|---|
| bank | string | شناسه بانک مربوط به شماره حساب |
| bankName | string | نام فارسی بانک برای نمایش به کاربر یا پشتیبانی |
| status | string | وضعیت حساب به‌صورت مقدار سیستمی |
| statusName | string | ترجمه خوانای وضعیت حساب |
| iban | string | شماره شبا |
| depositNumber | string | شماره حساب |
| owners | آرایه | فهرست صاحب یا صاحبان حساب متصل به شبا |
هر عضو آرایه owners دو بخش دارد:
| فیلد | نوع | توضیح |
|---|---|---|
| firstName | string | نام |
| lastName | string | نام خانوادگی |
مقدار status یکی از این حالت‌هاست: ACTIVE یعنی فعال؛ BLOCK_WITH_DEPOSIT یعنی حساب مسدود است اما قابلیت واریز دارد؛ BLOCK_WITHOUT_DEPOSIT یعنی حساب مسدود شده و قابلیت واریز ندارد؛ IDLE یعنی حساب راکد است؛ UNKNOWN یعنی نامشخص. فیلد statusName همان مفهوم را به فارسی برمی‌گرداند تا لایه نمایش مجبور نباشد جدول ترجمه داخلی نگه دارد.
برای منطق کسب‌وکار، روی status تصمیم بگیرید نه روی متن statusName. متن نمایشی ممکن است در رابط کاربری تغییر کند؛ مقدار سیستمی باید مبنای اجازه واریز، توقف تسویه یا ارجاع به بررسی دستی باشد. اگر حساب مسدود بدون قابلیت واریز یا راکد باشد، ادامه پرداخت خودکار معمولاً باید قطع شود. اگر فقط نام صاحب حساب برای تطبیق هویتی لازم است، روی آرایه owners کار کنید و فرض نکنید همیشه دقیقاً یک نفر برمی‌گردد.
bank برای منطق داخلی و مسیریابی بانکی مناسب‌تر است؛ bankName برای نمایش به کاربر نهایی و اپراتور پشتیبانی. depositNumber و iban را پس از پاسخ، دوباره با ورودی کاربر مقایسه کنید تا از دستکاری پاسخ یا باگ نگاشت در لایه میانی مطمئن شوید.
کدهای خطا API استعلام شبا و رفتار پیشنهادی کلاینت
خطاهای اعلام‌شده سرویس به این شکل است:
| کد / کلید خطا | توضیح |
|---|---|
| body_request.Invalid | بدنه درخواست خالی یا نامعتبر است |
| found_not.Iban | شبا یافت نشد |
| found_not_owner.Iban | صاحب شبا یافت نشد |
| Forbidden | غیرمجاز؛ توکن نامعتبر است یا حساب کاربری غیرفعال است |
| Iban.is_required | شبا الزامی است |
| Daily_limit.reached | در فراخوانی این سرویس به محدودیت روزانه رسیده‌اید |
| Iban.not_valid | شبا نامعتبر است |
| Providers.not_available | در حال حاضر سرویس‌دهنده در دسترس نیست |
| error.Serve | خطای داخلی سرور |
از نظر رفتار HTTP در کلاینت، این چهار وضعیت را جدا مدیریت کنید. در 400 معمولاً با بدنه خراب یا ورودی ناقص روبه‌رو هستید؛ درخواست را عیناً تکرار نکنید، بدنه و هدر Content-Type را اصلاح کنید. در 401 مسیر اخذ مجدد توکن، بررسی انقضای توکن و وضعیت فعال بودن حساب کاربری را طی کنید؛ صف پرداخت را با همان توکن مرده پر نکنید. در 422 ورودی از نظر کسب‌وکار یا اعتبار شبا قابل پردازش نیست؛ به کاربر پیام دقیق بدهید و از حلقه retry خودکار پرهیز کنید. در 429 یا رسیدن به محدودیت روزانه، backoff داشته باشید، مصرف را از گزارش پنل کنترل کنید و بار را روی بازه زمانی پخش کنید.
برای Providers.not_available و error.Serve، چند تلاش محدود با فاصله زمانی معقول قابل قبول است؛ اما سقف تلاش و مدارشکن (circuit breaker) را فراموش نکنید تا خطای بالادستی به thrashing در سرویس شما تبدیل نشود. پیام خام ارائه‌دهنده را مستقیم به کاربر نهایی نشان ندهید؛ آن را به پیام قابل‌فهم محصول و کد خطای داخلی خودتان نگاشت کنید و جزئیات فنی را فقط در لاگ عملیاتی نگه دارید.
Rate Limit استعلام شبا در عمل یعنی طراحی صف، کش کوتاه‌مدت برای تکرارهای یکسان در بازه مجاز کسب‌وکار، و جدا کردن ترافیک کاربری آنلاین از جابهای دسته‌ای. اگر جاب شبانه هزاران شبا را بدون کنترل شلیک کند، خیلی زود به Daily_limit.reached می‌رسید و مسیر آنلاین تسویه آسیب می‌بیند.
تفاوت کنترل ساختاری شبا با اعتبارسنجی واقعی سرویس
بسیاری از تیم‌ها ابتدا checksum و الگوی شبا را سمت خودشان چک می‌کنند. این کار درست است، اما فقط می‌گوید رشته ورودی از نظر ساختاری می‌تواند شبا باشد. ثابت نمی‌کند حساب واقعاً وجود دارد، فعال است، قابل واریز است یا به همان فردی تعلق دارد که در فرم ثبت شده است.
کنترل محلی معمولاً موارد زیر را پوشش می‌دهد: طول، پیشوند کشور، کاراکترهای مجاز و صحت رقم کنترلی. اعتبارسنجی سرویس، لایه بعدی را برمی‌گرداند: شناسه و نام بانک، شماره حساب، وضعیت حساب، و نام صاحبان. برای واریز و تسویه، تصمیم نهایی باید روی پاسخ سرویس باشد نه فقط پاس شدن الگوریتم محلی.
الگوی پیشنهادی این است: اول پاک‌سازی و اعتبارساختاری در کلاینت یا BFF، بعد فراخوانی API، بعد اعمال قواعد کسب‌وکار روی status و تطبیق owners. اگر فقط checksum را کافی بدانید، واریز به حساب مسدود یا راکد و مغایرت هویتی را دیر تشخیص می‌دهید؛ هزینه اصلاح آن در پشتیبانی و مالی معمولاً بالاتر از یک استعلام است.
نکات عملی برای یکپارچه‌سازی پایدار
Timeout و retry را صریح تعریف کنید. برای خطاهای ورودی و احراز هویت retry نکنید. برای خطای موقت بالادستی، تعداد تلاش را محدود و با جیتِر انجام دهید. پاسخ کامل را با همبستگی درخواست (correlation id) لاگ کنید، اما توکن و داده‌های حساس را ماسک کنید.
مدل داده داخلی‌تان را یک‌به‌یک به فیلدهای خام JSON قفل نکنید. یک لایه نگاشت داشته باشید تا اگر نام نمایشی بانک یا متن وضعیت برای UI تغییر کرد، منطق تسویه شما نشکند. روی مقادیر سیستمی status و وجود حداقل یک صاحب حساب، تست واحد و تست قرارداد بنویسید.
در محیط توسعه از توکن جدا و سهمیه جدا استفاده کنید. گزارش مصرف پنل را به مانیتورینگ داخلی وصل کنید تا قبل از رسیدن به سقف روزانه، هشدار بگیرید. برای تستهای یکپارچه، هم سناریوی حساب فعال و هم وضعیت‌های مسدود، راکد و نامشخص را پوشش دهید؛ فقط مسیر خوش‌بینانه را تست کردن، در تولید گران تمام می‌شود.
نمونه کد API استعلام شبا هر زبانی که باشد، باید همین حداقل‌ها را رعایت کند: HTTPS اجباری، هدر Authorization، JSON معتبر، مدیریت جداگانه ۴xx و خطاهای محدودیت، و تصمیم کسب‌وکار بر اساس status و owners. اگر چند سرویس داخلی از شبا استعلام می‌گیرند، فراخوانی را در یک کلاینت مشترک متمرکز کنید تا رفتار خطا و متریک‌ها یکدست بماند.
جمع‌بندی
مستندات فنی API استعلام شماره شبا وقتی به کار تیم می‌آید که endpoint، هدرها، بدنه، فیلدهای پاسخ و خطاها بدون ابهام پیاده شده باشند. قرارداد عملی نوین وان روشن است: GET https://api.novin.one/v1/ibans، توکن Bearer، کلید value برای شبا، و پاسخی شامل بانک، حساب، وضعیت و صاحبان. تفاوت checksum محلی با اعتبارسنجی سرویس را در طراحی لحاظ کنید، محدودیت روزانه را در معماری ترافیک ببینید، و خطاهای ۴۰۰، ۴۰۱، ۴۲۲ و ۴۲۹ را در کلاینت جدا مدیریت کنید.
اگر در حال ارزیابی یا اتصال عملیاتی هستید، جزئیات سرویس و مسیر دسترسی را در صفحه وب سرویس api استعلام شماره شبا بررسی کنید و یکپارچه‌سازی را روی همان قرارداد production-ready جلو ببرید.
