Skip to main content
#P1810

GET /b2c/v1/ledger-account

ledger-account

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

Endpoint Information

URL: /b2c/v1/ledger-account
Method: GET
Controller: CreditDebitController@ledgerAccount
Middleware: authWithJwt
Dependencies: ColleaguesController@colleagueLedgerAccounts, Redis, Morilog\Jalali\Jalalian

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

نام نوع الزامی توضیح
operator (JWT) object ✅ حاوی اطلاعات کاربر احراز شده، خصوصاً colleague_id
branch integer ✅ شناسه دفتر یا شعبه کاربر

منطق پردازشی (Flowchart)

📥 ۱. دریافت درخواست و استخراج شناسه همکار از JWT (operator->colleague_id)
↓
⚙️ ۲. ساخت پیش‌فرض‌های JSON جستجو (فیلتر زمانی و پارامترهای گزارش):
  • from = یک ماه قبل به تاریخ شمسی (با Jalalian::now()->subMonths(1))
  • to = تاریخ امروز
  • status = "0"
  • lbalance = false
↓
🧩 ۳. تزریق داده‌ی JSON تولیدشده در $request['json'] و $request['id'] سپس ایجاد نمونه از ColleaguesController و فراخوانی متد colleagueLedgerAccounts() برای واکشی جزئیات تراکنش‌ها.
↓
🗄️ ۴. واکشی مانده کلی حساب از Redis با کلید: colleagues:general_billing:all{colleague_id} در صورت موجود بودن داده، پارس آن با json_decode().
↓
بررسی وجود داده در Redis:
  • ✅ اگر موجود بود → ساخت آرایه شامل debit, credit, balance, diagnosis, documents از داده Redis
  • ❌ اگر نبود → مقادیر صفر پیش‌فرض تنظیم می‌شود
↓
✅ ۵. ساخت پاسخ JSON شامل لیست آیتم‌های دفتر کل و جزئیات موجودی: { items, payload, meta.timestamp }

ساختار خروجی 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 }
}

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

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

نکات فنی و باگ‌های شناسایی‌شده

  • اگر Redis کلید colleagues:general_billing:all{id} را نداشته باشد، پاسخ همواره با موجودی صفر ست می‌شود؛ بهتر است در این حالت سرویس colleagueLedgerAccounts برای جمع‌آوری داده‌ی جدید اجرا شود.
  • در نسخه فعلی، فیلد زمان‌ها و فرمت تاریخی بر اساس تاریخ شمسی با Morilog\Jalali تنظیم شده اما در سطح پایگاه داده (Carbon) تاریخ میلادی ذخیره می‌شود — نیاز به تطبیق هنگام sort در کلاینت دارد.
  • پاسخ دارای آرایه‌ای از آیتم‌های Ledger است که به‌صورت مستقیم از کنترلر همکار (`colleagueLedgerAccounts`) گرفته می‌شوند؛ در صورت تغییر ساختار آن متد، این خروجی نیز باید به‌روزرسانی شود.
  • بازگشت داده درون `meta.timestamp` با time() انجام می‌شود (یونیکس تایم).
Back to top