#P1711
POST /v2/trade/contract
Trade: Contract Generation
این اندپوینت وظیفه تولید متن کامل قرارداد را بر عهده دارد.
سیستم با استفاده از قالبهای HTML ذخیره شده در دیتابیس و ترکیب آنها با اطلاعات پویای فاکتور (مسافران، خدمات، قیمتها)، خروجی نهایی قرارداد را برای نمایش یا چاپ آماده میکند.
Request Overview
URL:
/v2/trade/contractMethod: POST
Controller: V2TradeController@contractTradeApi
Access Control
- نیاز به احراز هویت.
- بررسی دسترسی به `branch` ارسال شده.
Body Parameters
| Field | Type | Description |
|---|---|---|
| id | integer | (الزامی) شماره سریال نمایشی فاکتور. سیستم به صورت داخلی `ReferenceExtension` را از این عدد کم میکند تا سریال واقعی را در دیتابیس بیابد. |
| branch | integer | (الزامی) شناسه شعبه. |
| lang[id] | string | (الزامی) کد زبان برای انتخاب متن و قالب قرارداد (مثلاً `fa`). |
Logic Details
فرآیند تولید قرارداد شامل مراحل زیر است:
- واکشی اطلاعات پایه: جستجوی فاکتور با اتصال (Join) به جداول
operatorsوcustomersبر اساس سریال و شعبه. - اعتبارسنجیها:
- اگر
print == 0باشد، خطای "عدم قابلیت چاپ" (5006) برمیگرداند. - اگر
status == 5باشد، خطای وضعیت (5001) همراه با توضیحات فاکتور برمیگرداند.
- اگر
- انتخاب قالب (Template Engine):
- سیستم قالبی را از جدول
pagesانتخاب میکند کهtypeآن برابر باcontract_{route}باشد (مثلاًcontract_internal).
- سیستم قالبی را از جدول
- پردازش هوشمند آیتمها:
- محاسبه مجموع ارقام با استفاده از
ApiTradeController::financial. - مدیریت استرداد (Refund Logic): اگر آیتمی از نوع
refundباشد، آیتم اصلی متناظر با آن از لیست خدمات قرارداد حذف میشود تا سرویس کنسل شده نمایش داده نشود.
- محاسبه مجموع ارقام با استفاده از
- تولید جداول HTML: دو جدول به صورت پویا در کد ساخته میشوند:
%passengers-table%: لیست نام، کدملی و تاریخ تولد مسافران.%services-table%: لیست شرح خدمات باقیمانده.
- جایگذاری متغیرها: متغیرهایی مانند
%leader%,%total%,%company%در متن قالب جایگزین میشوند.
Response Structure
در صورت موفقیت، کد HTML قرارداد در فیلد contract و متادیتای مورد نیاز در data قرار میگیرد.
{
"status": true,
"time": 1715001200,
"contract": "... HTML CONTENT ...",
"data": {
"confirmation": "2024-05-10 12:30:00", // زمان تایید یا null
"serial_id": 1500, // شناسه اصلی دیتابیس
"internal": true, // وضعیت داخلی/خارجی بودن مسیر
"leader": {
"id": 105,
"firstname_en": "Ali",
"lastname_en": "Rezaei",
"firstname_fa": "علی",
"lastname_fa": "رضایی",
"mobile": "09121234567"
},
"slug": "xYz123",
"track_code": "02-2500", // فرمت: ماه - (سریال + اکستنشن)
"created": "2024-05-10 10:00:00"
}
}پاسخهای خطا
// خطای عدم وجود یا وضعیت نامعتبر
{
"status": false,
"code": 5001,
"message": "قرارداد یافت نشد"
}
// خطای غیرقابل چاپ بودن
{
"status": false,
"code": 5006,
"message": "رفرنس مورد نظر قابلیت چاپ ندارد."
}Flowchart
Start
↓
Query Factor (Join Ops/Cus)
↓
Factor Exists?
No
Error 5001
↓ (Yes)
Printable?
No
Error 5006
↓ (Yes)
Fetch Template
From `pages` table
From `pages` table
↓
Data Processing
1. Calculate Financials
2. Filter Refunds (Hide Cancelled Items)
3. Build HTML Tables (Pass/Service)
4. Replace %Placeholders%
1. Calculate Financials
2. Filter Refunds (Hide Cancelled Items)
3. Build HTML Tables (Pass/Service)
4. Replace %Placeholders%
↓
Return JSON + HTML