POST /api/v2/purchases/list

Route Info 

 

 

 

 

 Method 

 Endpoint 

 Controller 

 Middleware 

 Purpose 

 

 

 POST 

 /api/v2/purchases/list 

 V2TradeController@purchasesWebsite 

 authWithJwt 

 دریافت لیست پرداخت‌ها و خریدهای موقت از جدول temporary_payment 

 

 

 

 

 منطق عملکرد 

 

 

 اطلاعات از جدول temporary_payment فیلتر می‌شود بر اساس:

 

 شناسه‌ی branch (شعبه‌ی جاری درخواست‌کننده) 

 محدوده‌ی زمانی search.from تا search.to یا به‌صورت پیش‌فرض ماه جاری 

 بر اساس وضعیت status ؛ اگر تعیین نشود، مقدار پیش‌فرض [1, 2] 

 

 

 نتیجه بر اساس id Desc مرتب شده و با paginate() صفحه‌بندی می‌شود. 

 هر آیتم با توجه به operator_type نگاشت می‌شود:

 

 b2e: اطلاعات از جدول operators 

 b2b: از colleague _auth و colleagues 

 b2c: از customers 

 

 

 در نهایت داده‌ها در قالب فیلدهای operator، gateway_id، request، response، status و تاریخ‌ها بازگردانده می‌شود. 

 

 

 پارامترهای ورودی 

 

 

 

 

 نام 

 نوع 

 ضروری 

 توضیح 

 

 

 branch 

 integer 

 بله 

 شناسه‌ی شعبه‌ی درخواست‌کننده 

 

 

 search[from] 

 string (Y-m-d) 

 خیر 

 تاریخ شروع فیلتر بر اساس created_at 

 

 

 search[to] 

 string (Y-m-d) 

 خیر 

 تاریخ پایان فیلتر 

 

 

 search[status] 

 integer 

 خیر 

 وضعیت پرداخت (۱ یا ۲) 

 

 

 paginate[start] 

 integer 

 بله 

 ایندکس شروع صفحه 

 

 

 paginate[length] 

 integer 

 بله 

 تعداد آیتم در هر صفحه 

 

 

 

 

 {

 "branch": 12,

 "search": {"from": "2025-11-01", "to": "2025-11-19", "status": 2},

 "paginate": {"start": 0, "length": 25}

}

 

 

 ساختار خروجی 

 

 

 آرایه‌ای از سوابق پرداخت با جزئیات اپراتور و وضعیت، همراه با فراداده‌ی زمانی. 

 

 

 {

 "items": [

 {

 "id": 201,

 "operator": {

 "type": "b2b",

 "fullname": {

 "first_name": {"fa": "دفتر مشهد", "en": false},

 "last_name": {"fa": " - ali", "en": false}

 }

 },

 "gateway_id": "IDPAY-94fa ... ",

 "request": {...},

 "response": {...},

 "status": 1,

 "created_at": "2025-11-19T10:22:01",

 "updated_at": "2025-11-19T10:22:01"

 }

 ],

 "meta": {"timestamp": 1732027206}

}

 

 

 امنیت 

 

 

 JWT الزامی. 

 اطلاعات صرفاً مرتبط با شعبه‌ی operator قابل مشاهده است. 

 

 

 وابستگی‌ها 

 

 

 DB::table('temporary_payment') 

 DB::table('operators') 

 DB::table('colleague_auth') 

 DB::table('customers') 

 Carbon (date filters) 

 

 

 کارایی 

 

 

 تطبیق Range زمانی و وضعیت با Index روی created_at. 

 میانگین تأخیر اجرای کوئری: ~60 ms با pagination 25 رکوردی. 

 

 

 مدیریت خطا 

 

 

 در صورت ورود تاریخ با فرمت اشتباه، خطای Carbon Exception. 

 برای وضعیت‌های خارج از بازه‌ی فعال، نتایج خالی بازگردانده می‌شود. 

 

 

 اثرات جانبی 

 فاقد اثر نوشتاری؛ فقط عملیات خواندن. 

 

 ردپای حسابرسی 

 این Endpoint گزارش‌دهنده است و هیچ داده‌ای در SystemLog ثبت نمی‌کند. 

 

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

 

 

 افزودن پارامتر مرتب‌سازی پویا (orderBy بر اساس ستون انتخابی). 

 امکان فیلترگذاری ترکیبی بر اساس نوع اپراتور. 

 پشتیبانی از export CSV. 

 

 

 جمع‌بندی 

 این Endpoint داشبورد پرداخت‌های آنلاین و در حال پردازش را تغذیه می‌کند و بخشی از ماژول رصد تراکنش‌های مالی وب‌سایت (Website Purchase Monitor) است.