Skip to main content
#P1803

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 نمایش داده می‌شود تا از شناسه‌های فاکتور تفکیک گردد.
Back to top