# GET /b2c/v1/ledger-account

## ledger-account

این اندپوینت برای واکشی حساب کل دفتر همکار (colleague) در سیستم مالی B2C به‌کار می‌رود و از داده‌های تجمیع‌شده در Redis و خروجی متد `ColleaguesController::colleagueLedgerAccounts` استفاده می‌کند تا هم جزئیات صورت‌حساب‌ها (ledger items) و هم مانده‌ی کل حساب را برگرداند.

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

</div>### Endpoint Information

<div class="api-docs" id="bkmrk-url%3A-%2Fb2c%2Fv1%2Fledger-"><div class="endpoint-info"><div>**URL:** `/b2c/v1/ledger-account`</div><div>**Method:** <span class="method-get">GET</span></div><div>**Controller:** `CreditDebitController@ledgerAccount`</div><div>**Middleware:** `authWithJwt`</div><div>**Dependencies:** `ColleaguesController@colleagueLedgerAccounts`, `Redis`, `Morilog\Jalali\Jalalian`</div></div>---

</div>### پارامترهای ورودی

<div class="api-docs" id="bkmrk-%D9%86%D8%A7%D9%85-%D9%86%D9%88%D8%B9-%D8%A7%D9%84%D8%B2%D8%A7%D9%85%DB%8C-%D8%AA%D9%88%D8%B6%DB%8C%D8%AD"><table class="schema-table" dir="rtl"><thead><tr><th>نام</th><th>نوع</th><th>الزامی</th><th>توضیح</th></tr></thead><tbody><tr><td>operator (JWT)</td><td>object</td><td>✅</td><td>حاوی اطلاعات کاربر احراز شده، خصوصاً `colleague_id`</td></tr><tr><td>branch</td><td>integer</td><td>✅</td><td>شناسه دفتر یا شعبه کاربر</td></tr></tbody></table>

---

</div>### منطق پردازشی (Flowchart)

<div class="api-docs" id="bkmrk-%F0%9F%93%A5-%DB%B1.-%D8%AF%D8%B1%DB%8C%D8%A7%D9%81%D8%AA-%D8%AF%D8%B1%D8%AE%D9%88%D8%A7%D8%B3%D8%AA-"><div class="flowchart" dir="rtl"><div class="flow-item">📥 ۱. دریافت درخواست و استخراج شناسه همکار از JWT (`operator->colleague_id`)</div><div class="flow-arrow">↓</div><div class="flow-item-process">⚙️ ۲. ساخت پیش‌فرض‌های JSON جستجو (فیلتر زمانی و پارامترهای گزارش): - `from` = یک ماه قبل به تاریخ شمسی (با `Jalalian::now()->subMonths(1)`)
- `to` = تاریخ امروز
- `status` = "0"
- `lbalance` = false

</div><div class="flow-arrow">↓</div><div class="flow-item-process">🧩 ۳. تزریق داده‌ی JSON تولیدشده در `$request['json']` و `$request['id']` سپس ایجاد نمونه از **ColleaguesController** و فراخوانی متد **colleagueLedgerAccounts()** برای واکشی جزئیات تراکنش‌ها.</div><div class="flow-arrow">↓</div><div class="flow-item-process">🗄️ ۴. واکشی مانده کلی حساب از Redis با کلید: `colleagues:general_billing:all{colleague_id}` در صورت موجود بودن داده، پارس آن با `json_decode()`.</div><div class="flow-arrow">↓</div><div class="flow-item-decision">بررسی وجود داده در Redis: - ✅ اگر موجود بود → ساخت آرایه شامل debit, credit, balance, diagnosis, documents از داده Redis
- ❌ اگر نبود → مقادیر صفر پیش‌فرض تنظیم می‌شود

</div><div class="flow-arrow">↓</div><div class="flow-item-success">✅ ۵. ساخت پاسخ JSON شامل لیست آیتم‌های دفتر کل و جزئیات موجودی: `{ items, payload, meta.timestamp }`</div></div>---

</div>### ساختار خروجی JSON

#### پاسخ موفق

```json
{
  "items": [
    {
      "serial_id": "1404-22",
      "datetime": "1404/09/01 00:00:00",
      "credit": 500000,
      "debit": 0,
      "description": { "html": "واریز بابت فاکتور #22", "text": "واریز بابت فاکتور #22" },
      "details": { "type": { "title": "دریافت نقدی" } }
    }
  ],
  "payload": {
    "debit": 1250000,
    "credit": 500000,
    "balance": -750000,
    "diagnosis": "بدهکار",
    "documents": 17
  },
  "meta": { "timestamp": 1733768901 }
}
```

#### پاسخ بدون داده

```json
{
  "items": [],
  "payload": {
    "debit": 0,
    "credit": 0,
    "balance": 0,
    "diagnosis": 0,
    "documents": 0
  },
  "meta": { "timestamp": 1733768903 }
}
```

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

</div>### نکات فنی و باگ‌های شناسایی‌شده

<div class="api-docs" id="bkmrk-%D8%A7%DA%AF%D8%B1-redis-%DA%A9%D9%84%DB%8C%D8%AF-colle">- اگر Redis کلید `colleagues:general_billing:all{id}` را نداشته باشد، پاسخ همواره با موجودی صفر ست می‌شود؛ بهتر است در این حالت سرویس `colleagueLedgerAccounts` برای جمع‌آوری داده‌ی جدید اجرا شود.
- در نسخه فعلی، فیلد زمان‌ها و فرمت تاریخی بر اساس **تاریخ شمسی** با Morilog\\Jalali تنظیم شده اما در سطح پایگاه داده (Carbon) تاریخ میلادی ذخیره می‌شود — نیاز به تطبیق هنگام sort در کلاینت دارد.
- پاسخ دارای آرایه‌ای از آیتم‌های Ledger است که به‌صورت مستقیم از کنترلر همکار (`colleagueLedgerAccounts`) گرفته می‌شوند؛ در صورت تغییر ساختار آن متد، این خروجی نیز باید به‌روزرسانی شود.
- بازگشت داده درون `meta.timestamp` با `time()` انجام می‌شود (یونیکس تایم).

</div>