# POST /v2/account/bill

<div id="bkmrk-" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;"></div>### Route Info

<div id="bkmrk-method-endpoint-cont" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;"><div><table border="1" style="width: 100%; margin: auto; border-collapse: collapse; text-align: center; border: 1px solid #ddd;"><tbody><tr style="background: #f4f4f4; font-weight: bold;"><td style="padding: 10px;">Method</td><td style="padding: 10px;">Endpoint</td><td style="padding: 10px;">Controller</td></tr><tr><td style="direction: ltr; padding: 10px;">POST</td><td style="direction: ltr; padding: 10px;">/v2/account/bill</td><td style="direction: ltr; padding: 10px;">AccountingController@accountBill</td></tr></tbody></table>

</div></div>### شرح عملکرد (Functionality)

این متد وظیفه تولید "صورت‌حساب" (Statement of Account) را برای یک حساب خاص (گروه، کل، معین یا تفضیلی) بر عهده دارد. این تابع تراکنش‌های مالی را از منابع مختلف (اسناد پرداخت، چک‌ها، ارزش افزوده و اسناد افتتاحیه/اختتامیه) جمع‌آوری کرده، بدهکار/بستانکار بودن را محاسبه نموده و خروجی را جهت نمایش در جداول مالی آماده می‌کند. نکات فنی و منطقی آن عبارتند از:

<div id="bkmrk-%D8%AA%D8%B4%D8%AE%DB%8C%D8%B5-%D8%B3%D8%B7%D8%AD-%D8%AD%D8%B3%D8%A7%D8%A8-%28acco" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;">- **تشخیص سطح حساب (Accounting Titles):**
    - با استفاده از متد `getAccountingTitles`، کد حساب ورودی (`id`) تحلیل می‌شود.
    - طول کد سطح حساب را مشخص می‌کند: 2 رقم (گروه)، 4 رقم (کل)، 6 رقم (معین) و 9 رقم (تفضیلی).
    - وابستگی‌های حساب مانند "تفضیلی‌های شناور" (Detailed First Preferences) استخراج می‌شوند تا تراکنش‌های مرتبط با آن‌ها نیز در گزارش لحاظ شوند.
- **مدیریت تاریخ و فیلترها:**
    - اگر بازه تاریخی توسط کلاینت ارسال نشود، سیستم به صورت پیش‌فرض بازه "3 ماه اخیر" را در نظر می‌گیرد (مگر برای اپراتورهای خاص با ID‌های 34 و 52 که سال 1403 را کامل برمی‌گرداند).
    - تاریخ‌ها برای کوئری زدن به دیتابیس به فرمت میلادی (`created_at`) و شمسی (برای فیلدهای رشته‌ای مثل `deadline`) تبدیل می‌شوند.
- **منابع داده‌ای و منطق واکشی (Data Sources):** سیستم بر اساس تنظیمات `bill` در حساب معین، منابع زیر را پیمایش می‌کند: 
    - **Pays (اسناد دریافت/پرداخت):** کوئری اصلی روی جدول `pays` با شروط پیچیده روی تاریخ ایجاد و سررسید (Deadline).
    - **Check Operations (عملیات چک):** بررسی وضعیت‌های خاص چک (واگذاری، نقد شدن، برگشتی) با کدهای معین خاص (مثل `111202` و `111203`). از متد `getCheckOperationInManualDocument` برای استخراج جزئیات سند استفاده می‌شود.
    - **Value Added (ارزش افزوده):** محاسبه مالیات بر ارزش افزوده بر اساس "اعلامیه‌ها" (Announcements) و نرخ‌های ذخیره شده در `ACCOUNTING_VALUE_ADDED`.
    - **Marketing:** (در کد اشاره شده اما منطق کامل در قطعه کدها نیست).
- **سوابق مالی (Financial Pasts - Opening/Closing):**
    - سیستم با استفاده از `StaticController::getFinancialPasts` اسناد افتتاحیه و اختتامیه سال‌های مالی درخواست شده را استخراج می‌کند.
    - این اسناد با استفاده از `array_unshift` به ابتدای لیست تراکنش‌ها اضافه می‌شوند تا مانده از قبل (Balance) صحیح باشد.
    - از **Redis** برای کش کردن مقادیر افتتاحیه/اختتامیه استفاده می‌شود تا بار روی دیتابیس کاهش یابد.
- **محاسبه مانده و تشخیص (Credit/Debit logic):**
    - متد `StaticController::calculatorCreditDebit` برای هر سطر تعیین می‌کند که مبلغ باید در ستون بدهکار بنشیند یا بستانکار. این تشخیص بر اساس "ماهیت حساب" (Nature) و نوع تراکنش (Payment/Receive) انجام می‌شود.
    - در نهایت جمع کل بدهکار، بستانکار و مانده نهایی محاسبه شده و "تشخیص" حساب (Debtor/Creditor/Neutral) تعیین می‌شود.
    - نتیجه نهایی مانده حساب در Redis با کلید `accounting:account:balance:{code}` ذخیره می‌شود.
- **فرمت‌دهی خروجی (Formatting):**
    - جزئیات متنی تراکنش (مثل "بابت فاکتور شماره...") توسط `convertPayDetailsDbToTable` تولید می‌شود.
    - اگر تراکنش مربوط به یک "رفرنس" (تور/پرواز) باشد، لینک HTML به آن رفرنس تولید می‌شود.

</div>### پارامترهای ورودی (Input Parameters)

<div id="bkmrk-%D9%86%D8%A7%D9%85-%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1-%D9%86%D9%88%D8%B9-%D8%A7%D9%84%D8%B2%D8%A7" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;"><div><table border="1" style="width: 100%; border-collapse: collapse; text-align: right;"><thead><tr style="background: #f4f4f4;"><th style="padding: 8px;">نام پارامتر</th><th style="padding: 8px;">نوع</th><th style="padding: 8px;">الزامی؟</th><th style="padding: 8px;">توضیحات</th></tr></thead><tbody><tr><td style="direction: ltr;">id</td><td>Integer/String</td><td>بله</td><td>کد حساب مورد نظر (می‌تواند کد گروه، کل، معین یا تفضیلی باشد).</td></tr><tr><td style="direction: ltr;">type</td><td>String</td><td>خیر</td><td>نوع حساب (اختیاری، معمولا توسط خود کد شناسایی می‌شود).</td></tr><tr><td style="direction: ltr;">branch</td><td>Integer</td><td>بله</td><td>شناسه شعبه‌ای که صورت‌حساب آن درخواست شده است.</td></tr><tr><td style="direction: ltr;">json</td><td>JSON String</td><td>بله</td><td>آبجکت شامل تنظیمات فیلتر و صفحه‌بندی:   
`advanced.from`: تاریخ شروع (شمسی Y-m-d)   
`advanced.to`: تاریخ پایان (شمسی Y-m-d)   
`start`: آفست شروع (Pagination)   
`length`: طول صفحه</td></tr></tbody></table>

</div></div>### نمونه خروجی (Response)

```
{
    "Bills": [
        {
            "serial_id": 15100, // سریال نمایشی سند
            "system_serial": 101, // شناسه سیستمی رکورد
            "datetime": "1403/01/01 00:00:00",
            "credit": 0, // مبلغ بستانکار
            "debit": 5000000, // مبلغ بدهکار
            "details": {
                "title": {
                    "html": "سند افتتاحیه سال 1403 ...", // توضیحات با فرمت HTML
                    "text": "سند افتتاحیه سال 1403 ..."
                },
                "type": {
                    "subject": "financial_past",
                    "title": "افتتاحیه"
                }
            },
            "communications": false
        },
        {
            "serial_id": 2050,
            "system_serial": 5002,
            "datetime": "1403/05/10 12:30:00",
            "credit": 1200000,
            "debit": 0,
            "details": {
                "title": {
                    "html": "سند دریافت وجه نقد | بابت ...",
                    "text": "سند دریافت وجه نقد | بابت ..."
                },
                "type": {
                    "subject": "pay",
                    "title": "سندمالی"
                }
            }
        }
        // ... سایر ردیف‌ها
    ],
    "Total": {
        "credit": 1200000,
        "debit": 5000000,
        "balance": 3800000,
        "diagnosis": "Debtor" // وضعیت نهایی: Debtor (بدهکار)، Creditor (بستانکار)، Neutral (تراز)
    }
}
```