# POST /gateway/list

<div id="bkmrk-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### Route Info

<div id="bkmrk-method-endpoint-cont" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="width: 96%; margin: 15px auto; text-align: center; border-collapse: collapse;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>Method</td><td>Endpoint</td><td>Controller</td><td>Middleware</td><td>Purpose</td></tr><tr><td dir="ltr">POST</td><td dir="ltr">/api/v2/gateway/list</td><td dir="ltr">V2CreditDebitController@listGateway</td><td dir="ltr">authWithJwt</td><td dir="rtl">دریافت لیست درگاه‌های پرداخت فعال برای شعبه، با پشتیبانی از فیلتر و وضعیت تراکنش.</td></tr></tbody></table>

</div>### منطق عملکرد تابع

تابع **listGateway** برای واکشی تمامی درگاه‌های پرداخت متصل به شعبه و سیستم مالی طراحی شده است. با استفاده از ورودی DataTables، ابتدا پارامترهای فیلتر (مثل وضعیت، نوع درگاه، تاریخ ایجاد، یا شرکت) اعمال می‌گردند، سپس تراکنش‌های پرداختی اخیر مرتبط با هر درگاه از جدول `gateways` واکشی می‌شود.

در صورت فعال بودن سرویس تسویه خودکار، تابع داده‌ها را با نتیجه تسویه Redis ترکیب می‌کند تا وضعیت لحظه‌ای مانده هر درگاه نمایش داده شود.

<div id="bkmrk--1" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### ورودی‌ها

<div id="bkmrk-%D9%86%D8%A7%D9%85-%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1-%D9%86%D9%88%D8%B9-%D9%85%D9%86%D8%A8%D8%B9" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="width: 94%; margin: 15px auto; text-align: center; border-collapse: collapse;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>نام پارامتر</td><td>نوع</td><td>منبع</td><td>الزامی</td><td>توضیح</td></tr><tr><td>draw</td><td>integer</td><td>Body (DataTables)</td><td>بله</td><td>شماره درخواست برای هماهنگی پاسخ با DataTables.</td></tr><tr><td>length</td><td>integer</td><td>Body</td><td>بله</td><td>تعداد آیتم‌ها در هر صفحه.</td></tr><tr><td>start</td><td>integer</td><td>Body</td><td>بله</td><td>مقدار offset شروع لیست.</td></tr><tr><td>advanced</td><td>object</td><td>Body</td><td>خیر</td><td>فیلترهای پیشرفته (status, provider, type).</td></tr><tr><td>branch</td><td>integer</td><td>JWT/Header</td><td>بله</td><td>شناسه شعبه جهت واکشی درگاه‌ها.</td></tr></tbody></table>

</div>### خروجی (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
}
```

<div id="bkmrk--2" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### نکات امنیتی

<div id="bkmrk-%D8%AA%D9%88%DA%A9%D9%86-jwt-%D8%A8%D8%B1%D8%A7%DB%8C-%D8%B4%D9%86%D8%A7%D8%B3%D8%A7%DB%8C" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- توکن JWT برای شناسایی شعبه اجباری است.
- نمایش جزئیات تراکنش‌ها فقط برای نقش‌های دارای مجوز `financial.gateway.view`.
- درگاه‌های غیرفعال در خروجی حذف می‌شوند مگر نقش کاربر `developer` باشد.

</div>### نکات عملکردی

<div id="bkmrk-%D8%A7%D8%B3%D8%AA%D9%81%D8%A7%D8%AF%D9%87-%D8%A7%D8%B2-redis%3A%3Age" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- استفاده از `Redis::get('gateway:list:{branch}')` برای کش خروجی حدود ۶۰۰ ثانیه.
- در صورت حجم بالا (بیش از ۲۰ درگاه)، واکشی وضعیت تراکنش‌ها باید async باشد.
- کد SQL شامل ایندکس روی ستون‌های `branch` و `status` برای کاهش latency.

</div>### وابستگی‌ها

<div id="bkmrk-use-illuminate%5Csuppo" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- use Illuminate\\Support\\Facades\\DB;
- use Illuminate\\Support\\Facades\\Redis;
- use Carbon\\Carbon;
- use App\\Http\\Controllers\\StaticController;
- use App\\Helpers\\Functions;

</div>### کدهای خطا

<div id="bkmrk-%DA%A9%D8%AF-%D8%B4%D8%B1%D8%AD-%D8%AE%D8%B7%D8%A7-%D9%85%D9%86%D8%A8%D8%B9-400-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="width: 90%; margin: 15px auto; text-align: center; border-collapse: collapse;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>کد</td><td>شرح خطا</td><td>منبع</td></tr><tr><td>400</td><td>ورودی DataTables نامعتبر یا ناقص.</td><td>Validator</td></tr><tr><td>403</td><td>کاربر دسترسی مشاهده ندارد.</td><td>authWithJwt</td></tr><tr><td>500</td><td>خطا در Redis یا Query پایگاه داده.</td><td>DB Query</td></tr></tbody></table>

</div>### پیشنهادهای امنیتی

<div id="bkmrk-%D8%B1%D9%85%D8%B2%D9%86%DA%AF%D8%A7%D8%B1%DB%8C-%D8%B4%D9%86%D8%A7%D8%B3%D9%87-%D8%AF%D8%B1%DA%AF%D8%A7%D9%87" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- رمزنگاری شناسه درگاه در فرانت‌اند قبل از ارسال.
- اعمال Rate Limit ۱۰ درخواست در دقیقه به ازای هر IP.
- بررسی Double-fetch برای جلوگیری از حملات Enumeration.

</div>### پیشنهادهای بهبود

<div id="bkmrk-%D8%A7%D9%81%D8%B2%D9%88%D8%AF%D9%86-%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1-balan" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- افزودن پارامتر `balance_history:true` برای گزارش تغییرات موجودی.
- ترکیب مستقیم کش Redis با جدول تراکنش‌ها برای کاهش latency.
- پشتیبانی از درگاه‌های رمز‌ارز در فاز آینده.

</div>### ممیزی و لاگ‌ها

<div id="bkmrk-%D9%86%D9%88%D8%B9-%D9%84%D8%A7%DA%AF%3A-listgateway" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- نوع لاگ: `ListGateway`.
- فیلدهای ذخیره‌شده: `operator_id, branch, filter_used`.
- سطح لاگ: **Info**.
- نگهداری در جدول `audit_logs` تا ۳۰ روز.

</div>### جمع‌بندی

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

<div id="bkmrk-gateway-list" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>