#P1382

POST /api/v2/colleagues/billing

POSTRoute /api/v2/colleagues/billingInfo

این متد برای دریافت اطلاعات مالی کلی یک همکار (Colleague) یا پرسنل (Personnel) استفاده می‌شود. مسیر (Route) و میان‌افزارهای امنیتی آن به شرح زیر است:

~~بخش~~HTTP Method	~~توضیحات~~Route	Controller	Function	Middleware
~~آدرس مسیر~~POST	~~POST~~ /api/v2/colleagues/billing
~~کنترلر / تابع~~ColleaguesController	~~ColleaguesController →~~ ~~general_billingV2(Request $request)~~
~~میان‌افزارها (Middlewares)~~general_billingV2	~~domainAccess ,~~domainAccess, ipTrust

۱.Request تحلیل عملکردParameters

این ~~Route~~متد ~~برای~~یک ~~بازیابی اطلاعات صورتحساب عمومی همکاران در نسخه دوم API طراحی شده است. تابع بر اساس مقدار~~پارامتر ورودی اصلی با نام id ~~نوع شناسه~~ را ~~تشخیص~~از بدنه‌ی درخواست دریافت می‌~~دهد (colleague یا personnel) و با توجه به نوع، ماندهٔ اعتباری سال جاری را تولید و برمی‌گرداند.~~

۲. ورودی‌ها (Inputs)

کند.

~~فیلد~~نام پارامتر	نوع داده	~~اجباری~~الزامی	~~توضیح~~توضیحات
id	string	بله	شناسه مربوط به همکار یا پرسنل. دراگر ~~صورت~~مقدار ~~وجود کاراکتر~~شامل `-` باشد، نوع ~~شخص~~از ~~personnel~~مقدار ~~تشخیص داده~~استخراج می‌~~شود؛~~گردد، در غیر این صورت مقدار نوع برابر `colleague.` فرض می‌شود.

۳.Processing Logic

منطق عملکرد متد بر اساس کد موجود در کنترلر به شرح زیر می‌باشد:

ابتدا مقدار $request->id بررسی می‌شود.

اگر این مقدار شامل خط تیره (-) باشد، نوع (type) و شناسه (id) از آن استخراج می‌شود؛ در غیر این صورت نوع پیش‌فرض colleague در نظر گرفته می‌شود.

در صورتی که نوع برابر با colleague باشد، تابع CronController::colleaguesGeneralBilling($id) فراخوانی شده تا مانده سال جاری حساب محاسبه گردد.

خروجی ~~موفق (Successful Response - HTTP 200)~~
برای ~~همکاران~~نوع ~~(colleague):~~
colleague به‌صورت زیر است:

{
  "CreditLimit": 12000000,{credit_amount},
  "CreditBalance": 4500000{credit_amount - balance}
}

~~فیلد~~

~~CreditLimit~~

در ~~برابر~~صورتی ~~با مقدار~~که credit_amounttype = personnel ~~مدل~~باشد:

~~Colleague است.~~ ~~CreditBalance~~ ~~از تفاضل CreditLimit و مانده حساب برگردانده‌شده توسط~~ CronController::colleaguesGeneralBilling($id) ~~محاسبه می‌شود.~~

۴. خروجی برای پرسنل (personnel)

{
  "CreditLimit": false,
  "CreditBalance": false
}

۵.Error وابستگی‌ها (Dependencies)Handling

در

App\Http\Controllers\Api\CronController::colleaguesGeneralBilling($id)

صورتی

App\Models\Colleague

که

Morilog\Jalali\Jalalianشرکت ~~برای~~(همکار) ~~محاسبه~~یافت ~~تاریخ~~نشود ~~شمسی~~یا ~~جاری~~

اطلاعات

نادرست باشد، پاسخ زیر بازگردانده می‌شود:

~~۶. موارد خطا (Error Cases -~~

HTTP 200)

200

OK {"status":

~~شرط~~ ~~خروجی JSON~~

~~عدم یافتن همکار در جدول Colleague~~

{false, "message": "اطلاعات شرکت بدرستی ارسال نشده است." }

Response Example

نوع درخواست	کد وضعیت	نمونه پاسخ
موفق (Colleague)	200 OK	{ "CreditLimit": 5000000, "CreditBalance": 2750000 }
پرسنل	200 OK	{ "CreditLimit": false, "CreditBalance": false }

۷. شیوهٔ تست (Testing)

~~درخواست باید به صورت JSON ارسال شود:~~

POST /api/v2/colleagues/billing
Headers:
  Content-Type: application/json
Body:
{
  "id": "1234"
}

۸. خلاصه پیاده‌سازی (Implementation Summary)Notes

~~دریافت~~پاسخ ~~مقدار~~همواره $request->id

با

~~تشخیص~~وضعیت ~~نوع~~HTTP ~~شناسه~~200 بربازگردانده ~~اساس~~می‌شود، ~~وجود~~حتی ~~کاراکتر~~در

حالت خطا.
-

~~محاسبه~~این متد صرفاً جهت خواندن وضعیت مالی کل سال جاری ~~شمسی~~طراحی باشده Jalalian::forge('now')

است

~~اگر~~و ~~نوع~~هیچ ~~colleague:~~

~~واکشی Colleague با id~~

~~فراخوانی~~ colleaguesGeneralBilling()

~~محاسبه CreditBalance = CreditLimit - Balance~~

~~اگر نوع personnel → بازگرداندن خروجی ثابت false/false~~

~~🧩 مستند بالا کاملاً مطابق قالب HTML نهایی نسخهٔ ۱.۱ با قوانین چینش نهایی آماده درج~~تغییری در ~~Confluence~~داده‌های ~~است.~~

اصلی ایجاد نمی‌کند.
- محاسبه مانده و سقف اعتبار بر مبنای اطلاعات ثبت‌شده در حسابداری داخلی سیستم انجام می‌شود.