#P1415
POST /api/v2/trade/commitment/submit
Route Info
| Method | Endpoint | Controller | Middleware | Purpose |
| POST | /api/v2/trade/commitment/submit | V2TradeController@commitmentSubmitTrade | authWithJwt | ثبت یا بروزرسانی اطلاعات قرارداد تعهد در جدول contract و ثبت لاگ سیستمی |
منطق عملکرد
- در صورت وجود
page_id:- دادهی پیشین قرارداد از DB استخراج و نگهداری میشود.
- مقدار فیلد
dataدر جدول contract با JSON جدید بهروزرسانی میشود. - Job نوع
SystemLog::UpdateContractبا تأخیر ۱۰ دقیقه در صفsnailJobثبت میشود.
- در غیر این صورت (ثبت جدید):
- قرارداد جدید در جدول
contractدرج و شناسه آن بازگردانده میشود. - لاگ نوع
StoreContractایجاد میگردد.
- قرارداد جدید در جدول
- در پایان، پاسخ موفق شامل timestamp بازمیگردد.
- در صورت بروز Exception، پیام خطا و Trace برگردانده میشود.
پارامترهای ورودی
| نام | نوع | ضروری | توضیح |
| page_id | integer | خیر | شناسه قرارداد موجود (برای بروزرسانی) |
| page | integer | در حالت درج بله | شناسه صفحه قالب در جدول pages |
| object_type | string | بله | نوع شیء مرتبط (مثلاً pledger) |
| object | integer | بله | شناسه شیء مربوطه |
| data | object | بله | دادههای تکمیلشده قرارداد (فرم نهایی) |
{
"page_id": 18,
"object_type": "pledger",
"object": 154,
"data": {
"fullname": "علیرضا ایرانپور",
"national_code": "1234567890",
"installments": 8
}
}
ساختار خروجی
{
"status": true,
"time": 1732024850
}
در صورت خطا:
{
"status": false,
"message": "خطا در ارسال اطلاعات.",
"trace": [...]
}
امنیت
- احراز هویت اجباری توسط JWT.
- دسترسی فقط برای اپراتوری که قرارداد فاکتور را ایجاد کرده باشد.
- DB::table('contract')
- SystemLog::dispatch
- Carbon, Exception
- Queue: snailJob
کارایی
- عملیات درج/ویرایش بسیار سبک (زیر 20ms).
- Jobs با تأخیر در صف ثبت میشوند، بنابراین زمان پاسخ سریع است.
مدیریت خطا
- بلوک try/catch مانع از شکست کل درخواست میشود.
- بازگرداندن Trace برای دیباگ در محیط تست فعال است.
اثرات جانبی
- بهروزرسانی مستقیم جدول
contract. - ثبت jobهای لاگ سیستمی با تأخیر.
ردپای حسابرسی
تمام عملیات ذخیره و ویرایش قرارداد در قالب SystemLog ثبت میشود (نوع StoreContract یا UpdateContract) شامل by, ip, agent.
پیشنهادهای بهبود
- افزودن بررسی صحت ساختار داده ورودی (validation دقیق بر اساس Page Schema).
- افزودن اعلان پیامکی پس از ثبت (کدهای یادداشتشده آماده فعالسازی است).
جمعبندی
این Endpoint عملیات ذخیره و ویرایش دادههای قرارداد تعهد را مدیریت میکند و بههمراه SystemLog تضمین ردپای دقیق دارد. ترکیب منطقی این دو متد، جریان کامل «نمایش قرارداد → تأیید و ثبت نهایی» را میسازد.