# GET /b2c/v1/financial/list

## List Financial History

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

<div class="api-docs" id="bkmrk-"><div class="endpoint-section">  
</div>---

</div>### Endpoint Info

<div class="api-docs" id="bkmrk-url%3A-%2Fb2c%2Fv1%2Ffinanci"><div class="endpoint-info"><div>**URL:** `/b2c/v1/financial/list`</div><div>**Method:** <span class="method-get">GET</span></div><div>**Controller:** `CreditDebitController@listFinancial`</div><div>**Auth:** JWT Required (`middleware: authWithJwt`)</div></div>---

</div>### Query Parameters

<div class="api-docs" id="bkmrk-%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1-%D9%86%D9%88%D8%B9-%D8%A7%D8%AC%D8%A8%D8%A7%D8%B1%DB%8C-%D8%AA"><table class="schema-table" dir="rtl"><thead><tr><th>پارامتر</th><th>نوع</th><th>اجباری</th><th>توضیح</th></tr></thead><tbody><tr><td>group</td><td>string</td><td>✅</td><td>نوع گروه کاربری فعال. مقادیر مجاز: `b2c`, `b2b`, `colleague`.</td></tr><tr><td>branch</td><td>integer</td><td>❌</td><td>شناسه شعبه کاربر (مورد استفاده فقط برای B2B/Colleague).</td></tr><tr><td>operator.id</td><td>integer</td><td>✅</td><td>شناسهٔ کاربر یا اپراتور فعلی که از JWT تزریق می‌شود.</td></tr></tbody></table>

---

</div>### Logic Flow

<div class="api-docs" id="bkmrk-%F0%9F%93%A5-%D8%AF%D8%B1%DB%8C%D8%A7%D9%81%D8%AA-%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1%D9%87%D8%A7%DB%8C-"><div class="flowchart" dir="rtl"><div class="flow-item">📥 دریافت پارامترهای JWT شامل `operator.id` و `group`</div><div class="flow-arrow">↓</div><div class="flow-item-process">**۱. مسیر 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`

داده‌ها با وضعیت غیر از [۱،۲،۵] فیلتر می‌گردند.</div><div class="flow-arrow">↓</div><div class="flow-item-process">**۲. ترکیب داده با Redis Cache:**  
برای هر رکورد `pays`، مقدار توضیحات حسابداری از کلید `accounting:pays:{id}` در Redis واکشی می‌شود و در فیلد `description` درج می‌گردد.</div><div class="flow-arrow">↓</div><div class="flow-item-process">**۳. مسیر B2B / Colleague:**  
واکشی تراکنش‌های کیف پول (`wallet`) با شرط‌های زیر: - `branch = request.branch`
- `status = 1`
- `operator_type = 'b2b'`
- `operator = operator.id`

تراکنش‌ها در خروجی با فرمت: `id+10 000 ⇒ serial / tracking_code` و نوع تراکنش بر اساس `credit ≠ 0 ? 'receive' : 'payment'`.</div><div class="flow-arrow">↓</div><div class="flow-item-success">✅ در نهایت آرایهٔ خروجی `data` شامل لیست کامل تراکنش‌ها (دریافت، پرداخت، کیف‌پول، فاکتور) همراه با فیلدهای استاندارد مالی بازگردانده می‌شود.</div></div>---

</div>### Response Sample

```json
{
  "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"
    }
  ]
}
```

<div class="api-docs" id="bkmrk--1">---

</div>### Technical Notes

<div class="api-docs" id="bkmrk-%D8%AF%D8%A7%D8%AF%D9%87%E2%80%8C%D9%87%D8%A7-%D8%A7%D8%B2-redis-%DA%A9%D9%84%DB%8C">- داده‌ها از Redis کلید `accounting:pays:{id}` فقط اگر مقدار JSON معتبر باشد استخراج می‌گردند.
- در بخش B2C، فقط فاکتورهایی با وضعیت فعال (غیر از ۲ و ۵) در نظر گرفته می‌شوند.
- در صورت عدم وجود تراکنش، خروجی مقدار `data: []` بازمی‌گرداند و `status` همواره `true` است.
- تمام تاریخ‌ها در خروجی با فرمت `YYYYMMDD` محاسبه می‌شوند.
- تفاوت مقدار `fee` با مبلغ کل در تراکنش‌ها، کارمزد داخلی نیست و صفر برمی‌گردد مگر از Redis قابل استخراج باشد.
- برای B2B، شناسهٔ تراکنش کیف‌پول همیشه با offset ثابت `+10 000` در serial نمایش داده می‌شود تا از شناسه‌های فاکتور تفکیک گردد.

</div>