GET /b2c/v1/financial/list

List Financial History 

 این اندپوینت برای نمایش لیست تراکنش‌های مالی کاربران طراحی شده است و بسته به نوع گروه کاربری ( b2c یا b2b / colleague ) داده‌ها از جداول متفاوتی واکشی می‌گردند. برای کاربران B2C، از جداول factor_items ، factors و pays اطلاعات استخراج می‌شود و برای کاربران B2B/Colleague از جدول wallet . 

 

 

 

 Endpoint Info 

 

 

 URL: /b2c/v1/financial/list 

 Method: GET 

 Controller: CreditDebitController@listFinancial 

 Auth: JWT Required ( middleware: authWithJwt ) 

 

 

 Query Parameters 

 

 

 

 

 پارامتر 

 نوع 

 اجباری 

 توضیح 

 

 

 

 

 group 

 string 

 ✅ 

 نوع گروه کاربری فعال. مقادیر مجاز: b2c , b2b , colleague . 

 

 

 branch 

 integer 

 ❌ 

 شناسه شعبه کاربر (مورد استفاده فقط برای B2B/Colleague). 

 

 

 operator.id 

 integer 

 ✅ 

 شناسهٔ کاربر یا اپراتور فعلی که از JWT تزریق می‌شود. 

 

 

 

 

 Logic Flow 

 

 

 📥 دریافت پارامترهای JWT شامل operator.id و group 

 ↓ 

 ۱. مسیر B2C: 

 

 جستجوی فاکتورها در factor_items که customer_id = operator.id است یا در factors.customer = operator.id . 

 فاکتورها با وضعیت غیر از (۲،۵) انتخاب می‌شوند. 

 شناسه‌های فاکتور استخراج و با جدول pays ترکیب می‌شوند. 

 کوئری شامل تراکنش‌هایی با شرایط زیر است:

 

 type = 'receive' 

 object_type = 'reference' 

 object ∈ references 

 یا: functor_type = 'customer' و functor_account = operator.id 

 

 

 

داده‌ها با وضعیت غیر از [۱،۲،۵] فیلتر می‌گردند. 

 ↓ 

 ۲. ترکیب داده با Redis Cache: برای هر رکورد pays ، مقدار توضیحات حسابداری از کلید accounting:pays:{id} در Redis واکشی می‌شود و در فیلد description درج می‌گردد. 

 ↓ 

 ۳. مسیر B2B / Colleague: واکشی تراکنش‌های کیف پول ( wallet ) با شرط‌های زیر:

 

 branch = request.branch 

 status = 1 

 operator_type = 'b2b' 

 operator = operator.id 

 

تراکنش‌ها در خروجی با فرمت: id+10 000 ⇒ serial / tracking_code و نوع تراکنش بر اساس credit ≠ 0 ? 'receive' : 'payment' . 

 ↓ 

 ✅ در نهایت آرایهٔ خروجی data شامل لیست کامل تراکنش‌ها (دریافت، پرداخت، کیف‌پول، فاکتور) همراه با فیلدهای استاندارد مالی بازگردانده می‌شود. 

 

 

 Response Sample 

 {

 "status": true,

 "time": 1733751800,

 "data": [

 {

 "serial": 19087,

 "type": "receive",

 "type_pay": "reference",

 "deadline": "20251209",

 "currency": "IRR",

 "fee": 0,

 "amount": 2500000,

 "tracking_code": "TRX-19572",

 "description": {

 "reason": "پرداخت بابت فاکتور 17894",

 "gateway": "Parsian",

 "invoice": "Ref#X20991"

 }

 },

 {

 "serial": 26789,

 "type": "payment",

 "type_pay": "wallet",

 "deadline": "20251209",

 "currency": "IRR",

 "fee": 0,

 "amount": 1200000,

 "tracking_code": 26789,

 "description": "بابت هزینه خدمات هاب با عطف 2851"

 }

 ]

} 

 

 Technical Notes 

 

 

 داده‌ها از Redis کلید accounting:pays:{id} فقط اگر مقدار JSON معتبر باشد استخراج می‌گردند. 

 در بخش B2C، فقط فاکتورهایی با وضعیت فعال (غیر از ۲ و ۵) در نظر گرفته می‌شوند. 

 در صورت عدم وجود تراکنش، خروجی مقدار data: [] بازمی‌گرداند و status همواره true است. 

 تمام تاریخ‌ها در خروجی با فرمت YYYYMMDD محاسبه می‌شوند. 

 تفاوت مقدار fee با مبلغ کل در تراکنش‌ها، کارمزد داخلی نیست و صفر برمی‌گردد مگر از Redis قابل استخراج باشد. 

 برای B2B، شناسهٔ تراکنش کیف‌پول همیشه با offset ثابت +10 000 در serial نمایش داده می‌شود تا از شناسه‌های فاکتور تفکیک گردد.