#P1494
POST /gateway/list
Route Info
| Method | Endpoint | Controller | Middleware | Purpose |
| POST | /api/v2/gateway/list | V2CreditDebitController@listGateway | authWithJwt | دریافت لیست درگاههای پرداخت فعال برای شعبه، با پشتیبانی از فیلتر و وضعیت تراکنش. |
منطق عملکرد تابع
تابع listGateway برای واکشی تمامی درگاههای پرداخت متصل به شعبه و سیستم مالی طراحی شده است. با استفاده از ورودی DataTables، ابتدا پارامترهای فیلتر (مثل وضعیت، نوع درگاه، تاریخ ایجاد، یا شرکت) اعمال میگردند، سپس تراکنشهای پرداختی اخیر مرتبط با هر درگاه از جدول gateways واکشی میشود.
در صورت فعال بودن سرویس تسویه خودکار، تابع دادهها را با نتیجه تسویه Redis ترکیب میکند تا وضعیت لحظهای مانده هر درگاه نمایش داده شود.
ورودیها
| نام پارامتر | نوع | منبع | الزامی | توضیح |
| draw | integer | Body (DataTables) | بله | شماره درخواست برای هماهنگی پاسخ با DataTables. |
| length | integer | Body | بله | تعداد آیتمها در هر صفحه. |
| start | integer | Body | بله | مقدار offset شروع لیست. |
| advanced | object | Body | خیر | فیلترهای پیشرفته (status, provider, type). |
| branch | integer | JWT/Header | بله | شناسه شعبه جهت واکشی درگاهها. |
خروجی (Response)
{
"meta": { "timestamp": 1732287600, "draw": 1 },
"items": [
{
"id": 12,
"title": "Zarinpal Gateway",
"status": "active",
"transactions_count": 215,
"last_update": "1404/09/01 11:22",
"balance": {
"wallet": 48000000,
"pending": 1200000
}
}
],
"recordsTotal": 15,
"recordsFiltered": 15
}
نکات امنیتی
- توکن JWT برای شناسایی شعبه اجباری است.
- نمایش جزئیات تراکنشها فقط برای نقشهای دارای مجوز
financial.gateway.view. - درگاههای غیرفعال در خروجی حذف میشوند مگر نقش کاربر
developerباشد.
نکات عملکردی
- استفاده از
Redis::get('gateway:list:{branch}')برای کش خروجی حدود ۶۰۰ ثانیه. - در صورت حجم بالا (بیش از ۲۰ درگاه)، واکشی وضعیت تراکنشها باید async باشد.
- کد SQL شامل ایندکس روی ستونهای
branchوstatusبرای کاهش latency.
وابستگیها
- use Illuminate\Support\Facades\DB;
- use Illuminate\Support\Facades\Redis;
- use Carbon\Carbon;
- use App\Http\Controllers\StaticController;
- use App\Helpers\Functions;
کدهای خطا
| کد | شرح خطا | منبع |
| 400 | ورودی DataTables نامعتبر یا ناقص. | Validator |
| 403 | کاربر دسترسی مشاهده ندارد. | authWithJwt |
| 500 | خطا در Redis یا Query پایگاه داده. | DB Query |
پیشنهادهای امنیتی
- رمزنگاری شناسه درگاه در فرانتاند قبل از ارسال.
- اعمال Rate Limit ۱۰ درخواست در دقیقه به ازای هر IP.
- بررسی Double-fetch برای جلوگیری از حملات Enumeration.
پیشنهادهای بهبود
- افزودن پارامتر
balance_history:trueبرای گزارش تغییرات موجودی. - ترکیب مستقیم کش Redis با جدول تراکنشها برای کاهش latency.
- پشتیبانی از درگاههای رمزارز در فاز آینده.
ممیزی و لاگها
- نوع لاگ:
ListGateway. - فیلدهای ذخیرهشده:
operator_id, branch, filter_used. - سطح لاگ: Info.
- نگهداری در جدول
audit_logsتا ۳۰ روز.
جمعبندی
تابع listGateway با ترکیب دادههای حسابی و کش Redis، لیست مختصر و بهینهای از درگاههای فعال را بازمیگرداند. طراحی این مسیر با تمرکز بر سرعت واکشی و کنترل دسترسی دقیق انجام شده تا در محیطهای چندشعبهای و مالی پایدار بماند.