خلاصه مدیریتی
اصول، قراردادها و الزامات امنیتی طراحی APIهای REST در سامانه‌های بانکی بهسازان ملت؛ از نام‌گذاری منابع و نسخه‌بندی تا مدیریت خطا، صفحه‌بندی و Idempotency در تراکنش‌های مالی.
هدف و دامنه کاربرد
یکسان‌سازی طراحی رابط‌های برنامه‌نویسی همه سامانه‌های بانکی شرکت، به‌گونه‌ای که هر تیم بتواند APIهای تیم‌های دیگر را بدون مستند جداگانه و با کمترین خطا مصرف کند.
دامنه کاربرد
این راهنما برای همه APIهای REST داخلی و بیرونی در سامانه‌های همراه‌بانک، اینترنت‌بانک، بانکداری شرکتی و سرویس‌های پرداخت الزامی است. رابط‌های پیام‌محور مانند Kafka در مستند جداگانه‌ای پوشش داده می‌شوند.
پیش‌نیازها
- آشنایی با اصول HTTP و قالب JSON
- دسترسی به درگاه مدیریت API و محیط آزمایشی
- مطالعه چک‌لیست امنیتی پیش از استقرار سرویس‌ها
شرح دانش
نام‌گذاری منابع و مسیرها
مسیرها بر پایه منبع و با اسم جمع و حروف کوچک نوشته می‌شوند و نوع عملیات با فعل HTTP بیان می‌شود، نه در خود مسیر. از ساختار تودرتوی بیش از دو سطح پرهیز کنید تا مسیرها خوانا و قابل نگهداری بمانند.
- درست: GET /v1/accounts/{accountId}/transactions
- نادرست: POST /v1/getAccountTransactions
- شناسه‌ها همیشه در مسیر و فیلترها در پارامترهای پرس‌وجو قرار می‌گیرند
نسخه‌بندی و سازگاری
نسخه اصلی در ابتدای مسیر قرار می‌گیرد (v1، v2). تغییرات ناسازگار فقط در نسخه اصلی جدید منتشر می‌شوند و نسخه قبلی دست‌کم شش ماه پس از اعلام، با سرآیند Deprecation پشتیبانی می‌شود. افزودن فیلد اختیاری به پاسخ، تغییر سازگار به شمار می‌رود.
قالب استاندارد پاسخ خطا
همه خطاها با کد وضعیت HTTP مناسب و بدنه‌ای با ساختار یکسان بازگردانده می‌شوند. فیلد code برای پردازش ماشینی و فیلد message برای نمایش به کاربر نهایی است و هرگز نباید جزئیات فنی یا داده حساس را افشا کند.
{
"code": "ACCOUNT_INSUFFICIENT_BALANCE",
"message": "موجودی حساب برای انجام این تراکنش کافی نیست.",
"traceId": "7f3a9c2e41b84d0e",
"timestamp": "2026-11-03T08:15:42Z",
"details": [
{ "field": "amount", "reason": "EXCEEDS_AVAILABLE_BALANCE" }
]
}Idempotency در تراکنش‌های مالی
هر درخواست ایجاد تراکنش، مانند انتقال وجه، پرداخت قبض یا خرید شارژ، باید سرآیند Idempotency-Key را دریافت کند. سرویس با نگهداری کلید و نتیجه تا ۲۴ ساعت، در صورت تکرار درخواست همان پاسخ قبلی را بازمی‌گرداند و تراکنش دوباره ثبت نمی‌شود.
مراحل اجرا
- ۱
تعریف قرارداد پیش از توسعه
قرارداد API را با قالب OpenAPI 3 بنویسید و در مخزن قراردادها ثبت کنید. توسعه فقط پس از تأیید قرارداد آغاز می‌شود.
- ۲
بازبینی در کمیته معماری
قرارداد را برای بازبینی به تیم معماری سامانه‌ها ارسال کنید. بازبینی معمولاً ظرف دو روز کاری انجام می‌شود.
- ۳
پیاده‌سازی و آزمون قرارداد
آزمون‌های قرارداد را در خط استقرار فعال کنید تا هر انحراف از قرارداد پیش از انتشار شناسایی شود.
- ۴
انتشار در درگاه API
API را با سیاست‌های احراز هویت، محدودیت نرخ و ثبت رویداد در درگاه منتشر کنید و مستند آن را در فضای TECH پیوند دهید.
تصاویر و نمودارها
- ۱کانال‌هاهمراه‌بانک، اینترنت‌بانک
- ۲درگاه APIاحراز هویت، محدودیت نرخ
- ۳سرویس‌های دامنهحساب، پرداخت، کارت
- ۴هسته بانکیثبت نهایی تراکنش
نکات تخصصی
برای فهرست‌های بزرگ، صفحه‌بندی مبتنی بر نشانگر (Cursor) را به صفحه‌بندی عددی ترجیح دهید؛ در جدول‌های تراکنشی سریع‌تر و پایدارتر است.
مقادیر مالی را به‌صورت عدد صحیح و به کوچک‌ترین واحد پول منتقل کنید تا خطای گردکردن رخ ندهد.
شناسه رهگیری را در همه لاگ‌ها و پاسخ‌های خطا بازگردانید تا عیب‌یابی میان تیم‌ها سریع‌تر شود.
نظرات و بازخورد همکاران۳
بخش Idempotency دقیقاً همان چیزی بود که در سرویس‌های پرداخت کم داشتیم. پیشنهاد می‌کنم مدت نگهداری کلید برای تراکنش‌های تسویه را هم مشخص کنید.
ممنون از پیشنهاد. برای تسویه ۷۲ ساعت در نظر داریم و در نسخه بعدی اضافه می‌کنم.
تیم همراه‌بانک از قالب خطای جدید استفاده کرد و نمایش پیام‌ها به کاربر بسیار یکدست‌تر شد.