Skip to main content
#P1399

POST /api/v2/references/{type}/list

Route Info

Method Endpoint Controller Middleware Purpose
POST /api/v2/references/{type}/list V2TradeController@referenceCreditDebit authWithJwt دریافت لیست مراجع مالی (بدهکار/بستانکار) بر اساس نوع و جستجوی دلخواه

منطق عملکرد و مسیر داده

  • تابع referenceCreditDebit مقدار مسیر {type} را بررسی کرده و نوع credit یا debit را مشخص می‌کند.
  • بر اساس مقدار type، داده‌های مرتبط از جداول مرجع مربوط (مانند Reference، FinanceAccount یا کش Redis) واکشی می‌شود.
  • در صورت وجود کلیدهای filter، فیلترینگ سطح دیتابیس یا cached data انجام می‌شود.
  • تمام آیتم‌ها با متدهای کمکی Formatted و با ساختار استاندارد JSON بازگردانده می‌شوند.
  • اگر مقدار type اشتباه داده شود یا خالی باشد، خروجی با کد خطای 1000 و پیام خطا برمی‌گردد.

ورودی‌ها (Request Fields)

نام فیلد نوع داده ضروری توضیح
type string بله نوع منبع مالی: credit یا debit
filter object|null خیر فیلترهای انتخابی، مثل active=true یا company_id

نمونه درخواست:

{
  "filter": { "company_id": 12, "active": true }
}

خروجی (Response Structure)

فیلد نوع داده توضیح
status string وضعیت پاسخ (success یا error)
message string پیام وضعیت
data array آرایه‌ای از مراجع مالی فیلترشده

نمونه پاسخ موفق:

{
  "status": "success",
  "message": "Reference list retrieved successfully",
  "data": [
    { "id": 1, "title": "بانک ملت", "type": "credit", "balance": 3200000 },
    { "id": 2, "title": "مشتری ویژه", "type": "debit", "balance": -170000 }
  ]
}

نمونه پاسخ خطا:

{
  "status": "error",
  "message": "Invalid type parameter"
}

تحلیل امنیتی و کنترل خطا

  • فقط کاربران احراز هویت‌شده با JWT می‌توانند به این مسیر درخواست بفرستند.
  • در صورت تقلب در مقدار type یا ارسال داده مخرب در filter (مانند SQL Injection)، تابع مقدار نامعتبر را رد می‌کند.
  • در نسخه حاضر هیچ throttle یا rate-limit اعمال نشده است؛ پیشنهاد می‌شود پس از فعال‌سازی در نسخه بعدی.

نکات کارایی

  • درصورت فعال بودن Redis cache، سرعت پاسخ‌دهی زیر ۳۰ میلی‌ثانیه است.
  • درصورت نبود cache یا فیلتر dynamic، کوئری روی جدول Reference اجرا می‌شود.
  • در صورت حجم زیاد داده‌ها، پیشنهاد استفاده از pagination.

وابستگی‌های کلیدی

  • use Illuminate\\Support\\Facades\\Redis;
  • use App\\Models\\Reference;
  • use App\\Helpers\\Functions;
  • use App\\Http\\Controllers\\Api\\Panel\\V2\\V2TradeController;

کدهای خطا و حالت‌های Exception

کد خطا شرح منبع
1000 پارامتر type نامعتبر است referenceCreditDebit logic
1002‑1006 JWT نامعتبر یا منقضی / دسترسی غیرمجاز authWithJwt middleware
500 Database / Redis Exception referenceCreditDebit

پیشنهادهای بهبود

  • افزودن TTL به cache لیست مراجع برای جلوگیری از stale data.
  • اضافه‌کردن validation ساختاری برای filter object.
  • پشتیبانی از pagination برای داده‌های حجیم.
  • ثبت log زمانی برای مانیتورینگ درخواست‌های مکرر بر اساس کاربر.

جمع‌بندی

این Endpoint برای واکشی سریع و ساده مراجع مالی طراحی شده است. با ساختار JSON استاندارد و پشتیبانی از فیلترگذاری ساده در عین حال با قابلیت افزودن cache – بهینه و سریع است. با افزودن لایه validation و TTL در cache می‌تواند کاملاً پایدار و قابل اطمینان در سیستم مالی شود.
Back to top