#P1580
POST /v2/account/bill
Route Info
| Method |
Endpoint |
Controller |
| POST |
/v2/account/bill |
AccountingController@accountBill |
شرح عملکرد (Functionality)
این متد وظیفه تولید "صورتحساب" (Statement of Account) را برای یک حساب خاص (گروه، کل، معین یا تفضیلی) بر عهده دارد. این تابع تراکنشهای مالی را از منابع مختلف (اسناد پرداخت، چکها، ارزش افزوده و اسناد افتتاحیه/اختتامیه) جمعآوری کرده، بدهکار/بستانکار بودن را محاسبه نموده و خروجی را جهت نمایش در جداول مالی آماده میکند. نکات فنی و منطقی آن عبارتند از:
- تشخیص سطح حساب (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 به آن رفرنس تولید میشود.
پارامترهای ورودی (Input Parameters)
| نام پارامتر |
نوع |
الزامی؟ |
توضیحات |
| id |
Integer/String |
بله |
کد حساب مورد نظر (میتواند کد گروه، کل، معین یا تفضیلی باشد). |
| type |
String |
خیر |
نوع حساب (اختیاری، معمولا توسط خود کد شناسایی میشود). |
| branch |
Integer |
بله |
شناسه شعبهای که صورتحساب آن درخواست شده است. |
| json |
JSON String |
بله |
آبجکت شامل تنظیمات فیلتر و صفحهبندی:
advanced.from: تاریخ شروع (شمسی Y-m-d)
advanced.to: تاریخ پایان (شمسی Y-m-d)
start: آفست شروع (Pagination)
length: طول صفحه |
نمونه خروجی (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 (تراز)
}
}
