# POST /v2/trade/contract

# Trade: Contract Generation

این اندپوینت وظیفه **تولید متن کامل قرارداد** را بر عهده دارد.   
سیستم با استفاده از قالب‌های HTML ذخیره شده در دیتابیس و ترکیب آن‌ها با اطلاعات پویای فاکتور (مسافران، خدمات، قیمت‌ها)، خروجی نهایی قرارداد را برای نمایش یا چاپ آماده می‌کند.

<div class="api-docs" id="bkmrk-"></div>## Request Overview

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Ftrade%2Fcontr"><div class="endpoint-info"><div>**URL:** `/v2/trade/contract`</div><div>**Method:** <span class="method-post">POST</span></div><div>**Controller:** V2TradeController@contractTradeApi</div></div></div>## Access Control

<div class="api-docs" id="bkmrk-%D9%86%DB%8C%D8%A7%D8%B2-%D8%A8%D9%87-%D8%A7%D8%AD%D8%B1%D8%A7%D8%B2-%D9%87%D9%88%DB%8C%D8%AA.-">- نیاز به احراز هویت.
- بررسی دسترسی به `branch` ارسال شده.

</div>## Body Parameters

<div class="api-docs" id="bkmrk-field-type-descripti"><table class="schema-table" dir="rtl"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>integer</td><td>**(الزامی)** شماره سریال نمایشی فاکتور.   
<small>سیستم به صورت داخلی `ReferenceExtension` را از این عدد کم می‌کند تا سریال واقعی را در دیتابیس بیابد.</small></td></tr><tr><td>branch</td><td>integer</td><td>**(الزامی)** شناسه شعبه.</td></tr><tr><td>lang\[id\]</td><td>string</td><td>**(الزامی)** کد زبان برای انتخاب متن و قالب قرارداد (مثلاً `fa`).</td></tr></tbody></table>

</div>## Logic Details

فرآیند تولید قرارداد شامل مراحل زیر است:

<div class="api-docs" id="bkmrk-%D9%88%D8%A7%DA%A9%D8%B4%DB%8C-%D8%A7%D8%B7%D9%84%D8%A7%D8%B9%D8%A7%D8%AA-%D9%BE%D8%A7%DB%8C%D9%87%3A-">1. **واکشی اطلاعات پایه:** جستجوی فاکتور با اتصال (Join) به جداول `operators` و `customers` بر اساس سریال و شعبه.
2. **اعتبارسنجی‌ها:**
    - اگر `print == 0` باشد، خطای "عدم قابلیت چاپ" (5006) برمی‌گرداند.
    - اگر `status == 5` باشد، خطای وضعیت (5001) همراه با توضیحات فاکتور برمی‌گرداند.
3. **انتخاب قالب (Template Engine):**
    - سیستم قالبی را از جدول `pages` انتخاب می‌کند که `type` آن برابر با `contract_{route}` باشد (مثلاً `contract_internal`).
4. **پردازش هوشمند آیتم‌ها:**
    - محاسبه مجموع ارقام با استفاده از `ApiTradeController::financial`.
    - **مدیریت استرداد (Refund Logic):** اگر آیتمی از نوع `refund` باشد، آیتم اصلی متناظر با آن از لیست خدمات قرارداد حذف می‌شود تا سرویس کنسل شده نمایش داده نشود.
5. **تولید جداول HTML:** دو جدول به صورت پویا در کد ساخته می‌شوند: 
    - `%passengers-table%`: لیست نام، کدملی و تاریخ تولد مسافران.
    - `%services-table%`: لیست شرح خدمات باقی‌مانده.
6. **جایگذاری متغیرها:** متغیرهایی مانند `%leader%`, `%total%`, `%company%` در متن قالب جایگزین می‌شوند.

</div>## Response Structure

در صورت موفقیت، کد HTML قرارداد در فیلد `contract` و متادیتای مورد نیاز در `data` قرار می‌گیرد.

```json
{
  "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"
  }
}
```

### پاسخ‌های خطا

```json
// خطای عدم وجود یا وضعیت نامعتبر
{
  "status": false,
  "code": 5001,
  "message": "قرارداد یافت نشد" 
}
// خطای غیرقابل چاپ بودن
{
  "status": false,
  "code": 5006,
  "message": "رفرنس مورد نظر قابلیت چاپ ندارد."
}
```

<div class="api-docs" id="bkmrk--1"></div>## Flowchart

<div class="api-docs" id="bkmrk-start-%E2%86%93-query-factor"><div class="flowchart"><div class="flow-item">Start</div><div class="flow-arrow">↓</div><div class="flow-item-process">Query Factor (Join Ops/Cus)</div><div class="flow-arrow">↓</div><div class="flow-item-decision">Factor Exists?</div><div style="position: relative;"><div class="flow-arrow-label-right" style="top: -20px; right: -50px;">No</div><div class="flow-item-error" style="float: right; margin-right: -140px; width: 120px;">Error 5001</div></div><div class="flow-arrow">↓ (Yes)</div><div class="flow-item-decision">Printable?</div><div style="position: relative;"><div class="flow-arrow-label-right" style="top: -20px; right: -50px;">No</div><div class="flow-item-error" style="float: right; margin-right: -140px; width: 120px;">Error 5006</div></div><div class="flow-arrow">↓ (Yes)</div><div class="flow-item-process">**Fetch Template**  
From `pages` table</div><div class="flow-arrow">↓</div><div style="background-color: #e3f2fd; padding: 10px; border-radius: 8px;">**Data Processing**  
1. Calculate Financials  
2. Filter Refunds (Hide Cancelled Items)  
3. Build HTML Tables (Pass/Service)  
4. Replace %Placeholders%</div><div class="flow-arrow">↓</div><div class="flow-item-success">Return JSON + HTML</div></div></div>