#P1515
POST /colleague/bill
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| POST |
/api/v2/colleague/bill |
V2ColleaguesController@colleagueBill |
authWithJwt |
دریافت صورتحساب مالی یک همکار (Colleague) شامل تراکنشهای پرداخت، دریافت، چک، کارمزد و مانده دوره. |
منطق عملکرد تابع
تابع colleagueBill فهرستی از اسناد مالی مرتبط با یک همکار خاص را بر اساس id همکار و بازه تاریخی درخواستشده برمیگرداند. الگوریتم شامل مراحل زیر است:
- خواندن ساختار JSON ورودی شامل فیلترها (from, to, r, status, lbalance, fpopen) برای محدودسازی بازهٔ تراکنش.
- بازیابی فاکتورهای صادرشده از جداول مرتبط (فروش، خدمات و رزرو) و سپس عملیات پرداخت یا دریافت از جدول
pays.
- تشخیص خودکار نوع عملیات مالی (پرداخت، دریافت، چک، سند دستی، کارمزد، افتتاحیه، اختتامیه).
- محاسبه مجموع بستانکاری و بدهکاری برای هر فاکتور و تولید خروجی یکپارچه شامل عنوان، تاریخ، توضیحات HTML و نوع سند.
- در صورت فعال بودن گزینه «lbalance»، مانده دوره قبل با عنوان «مانده دوره قبل تا تاریخ X/X/X» در بالای خروجی درج میشود.
- تمامی دادهها قبل از بازگردانی، بر اساس زمان شمسی (Jalalian) مرتبسازی صعودی میشوند.
ورودیها
| نام |
نوع |
منبع |
الزامی |
توضیح |
| json |
string (JSON) |
Body |
بله |
شامل فیلترهای صفحهبندی و بازه تاریخی. |
| id |
integer |
Body |
بله |
شناسه همکار مورد نظر برای استخراج صورتحساب. |
| branch |
string |
Body |
خير |
شناسه شعبه (در صورت فیلتر مالی). پیشفرض: شعبه کاربر فعلی. |
| advanced.from |
string (Y-m-d) |
Body |
خیر |
تاریخ شروع بازه گزارش. |
| advanced.to |
string (Y-m-d) |
Body |
خیر |
تاریخ پایان بازه گزارش. |
| advanced.r |
string/integer |
Body |
خیر |
شماره سریال خاص برای جستجوی مستقیم. |
| advanced.lbalance |
boolean |
Body |
خیر |
فعالسازی نمایش مانده دوره قبل. |
| advanced.fpopen |
boolean |
Body |
خیر |
نمایش اسناد افتتاحیه در ابتدای دفتر حساب. |
ساختار خروجی
{
"recordsTotal": 54,
"details": {
"id": 202,
"title": "آژانس مهر و ماه",
"category": "شرکت داخلی",
"type": "شریک تجاری (بستانکار)"
},
"total": {
"credit": 22650000,
"debit": 13790000
},
"data": [
{
"serial_id": "28-202",
"datetime": "1404/06/20 09:00:00",
"credit": 2500000,
"debit": 0,
"description": {
"html": "دریافت چک از دفتر مرکزی",
"text": "دریافت چک از دفتر مرکزی"
},
"details": {
"documents": { "pay": 914 },
"type": { "subject": "check_paid", "title": "چک نقدی" }
},
"relationship": null,
"communications": false
}
]
}
نکات امنیتی
- این مسیر فقط برای کاربران احراز هویتشده (JWT معتبر) در دسترس است.
- دادهها فقط از محدودهٔ شعبه کاربر قابل دسترس است.
- در اطلاعات بازگشتی هیچ دادهٔ محرمانه بانکی ذخیره نمیشود.
نکات عملکردی
- الگوریتم با صفحهبندی پایگاه داده (
paginate) بهینهسازی شده است.
- فیلتر تاریخ شمسی با کلاس
Morilog\Jalali\Jalalian تبدیل و استفاده میشود.
- در هر مرحله زمان عملیات با microtime برای تحلیل عملکرد ثبت میشود.
وابستگیها
- use Morilog\Jalali\Jalalian;
- use Carbon\Carbon;
- use Illuminate\Support\Facades\DB;
- use Illuminate\Support\Facades\Redis;
- use App\Http\Controllers\ApiColleaguesController;
- use App\Http\Controllers\Functions;
کدهای خطا
| کد |
شرح خطا |
منبع |
| 401 |
توکن JWT نامعتبر یا منقضی. |
authWithJwt |
| 404 |
یافت نشدن همکار. |
Database Query |
| 500 |
خطا در پردازش تاریخ یا تجمع دادهها (Jalalian/Carbon). |
Logic Exception |
پیشنهادهای امنیتی
- ایزولهسازی دادههای «چک برگشتی» از خروجی اصلی جهت جلوگیری از افشای نام اشخاص.
- رمزنگاری مسیر دسترسی به اسناد صورتحساب در Redis Cache.
پیشنهادهای توسعهای
- افزودن پارامتر
with_closing برای کنترل نمایش اختتامیهها.
- افزودن فیلتر نوع سند (
subject_type) برای جستجوی دقیقتر.
- ایجاد قابلیت export به XLSX/CSV.
ممیزی و لاگها
- نوع لاگ:
ColleagueBill.
- جزئیات ثبتشده: user_id، colleague_id، بازه تاریخی، مجموع بدهکار/بستانکار.
- سطح حساسیت: High.
جمعبندی
تابع colleagueBill یکی از سنگینترین و حیاتیترین مسیرهای مالی در سیستم است که ترکیبی از پرداختها، چکها، اسناد دستی و مانده دوره را در قالب یک جمعبندی زمانی بازمیگرداند. امنیت و صحت زمانبندی محاسباتی نقش کلیدی در جلوگیری از ناسازگاریهای حسابداری دارد.
