#P1414
POST /api/v2/trade/commitment
Route Info
| Method | Endpoint | Controller | Middleware | Purpose |
| POST | /api/v2/trade/commitment | V2TradeController@commitmentTrade | authWithJwt | تولید محتوای قرارداد مالی (Commitment) بر پایهی رکورد تعهدکننده در فاکتور و الگوی قرارداد شعبه |
منطق عملکرد
- شناسه زبان از
$request['lang']['id']گرفته میشود. - تابع درونی
computingInstallments()با محاسبهی مبلغ و تعداد اقساط (۴،۸،۱۲) محتوای HTML متغیر اقساط را ایجاد میکند. - تعهدکننده (
pledger) بر اساسpledger_idواکشی میشود. - در صورتی که ردیف معتبر بود:
- فاکتور مرتبط از جداول
factors, operators, customersاستخراج میشود. - الگوی قرارداد از جدول
pagesباtype='contract_colleague_161'بارگذاری میشود. - اطلاعات فاکتور و دادههای داینامیک با مقادیر موجود در
$contractDb->dataیا در صورت عدم وجود، مقادیر پیشفرض جایگزین میشوند. - تمام Placeholderهای متنی (٪leader٪ ... ٪installments٪ و ...) در قالب قرارداد جایگزین میگردند.
- پاسخ JSON شامل HTML نهایی قرارداد و دادههای تکمیلی برگردانده میشود.
- فاکتور مرتبط از جداول
- در صورت خطا (فاکتور غیرفعال یا صفحه ناموجود) کد 404 با پیام مناسب بازگردانده میشود.
پارامترهای ورودی
| نام | نوع | ضروری | توضیح |
| pledger_id | integer | بله | شناسهی تعهدکننده (ردیف جدول pledgers) |
| branch | integer | بله | شناسهی شعبه جاری برای یافتن صفحهی قالب قرارداد |
| lang.id | integer | بله | شناسه زبان خروجی قرارداد |
{
"pledger_id": 154,
"branch": 12,
"lang": {"id": 1}
}
ساختار خروجی
- status: وضعیت موفقیت درخواست
- contract: محتوای HTML کامل قرارداد با جایگزینی دادهها
- data: شامل اطلاعات صفحه، تأییدیه و مشخصات فاکتور متعهد
{
"status": true,
"time": 1732024532,
"contract": "<html>...</html>",
"data": {
"page_details": {"page":18,"object_type":"pledger","object":154},
"confirmation": 1,
"serial_id": 13521,
"internal": true,
"leader": {...},
"slug": "a9cD91bc",
"track_code": "05-11023"
}
}
امنیت
- تحت محافظت Middleware
authWithJwt. - دسترسی فقط برای کاربرانی که شعبهی مرتبط دارند.
- در خروجی هیچ دادهی حساسی از قرارداد اصلی لو نمیرود.
وابستگیها
- DB::table('pledgers')
- DB::table('factors')
- DB::table('pages')
- Functions, Jalalian, StaticController, Carbon
کارایی
- متوسط زمان پاسخ: 70–90ms (اصلی بار پردازش متن قرارداد).
- بدون اعمال تراکنش سنگین DB.
مدیریت خطا
- فاکتور نامعتبر → code 5006
- صفحه قرارداد پیدا نشد → code 5001
- در صورت
status != 5یاprint == 0خروجی خطای منطقی بازگردانده میشود.
اثرات جانبی
خواندن داده از contract و pages. هیچ درج یا بروزرسانیای انجام نمیشود (Read‑Only).
ردپای حسابرسی
در این متد لاگ مستقیم ثبت نمیشود. مسیر بعدی commitmentSubmitTrade مسئول logging اقدامات کاربر در جدول SystemLog است.
پیشنهادهای بهبود
- تفکیک تابع
computingInstallments()به یک Helper مستقل در لایه Service. - افزودن کش سمت Redis برای صفحات قرارداد.
جمعبندی
این Endpoint خروجی HTML قرارداد مالی براساس اطلاعات فاکتور و تعهدکننده را تهیه میکند و مرحلهی مقدماتی قبل از ثبت در دیتابیس است. خروجی آمادهی چاپ یا نمایش به کاربر نهایی در فرانتاند میباشد.