# POST /v2/trade/tickets

# Trade: Tickets & Vouchers Data

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

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

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

<div class="api-docs" id="bkmrk-%D8%AF%D8%B3%D8%AA%D8%B1%D8%B3%DB%8C-%D8%B9%D9%85%D9%88%D9%85%DB%8C-%28public">- دسترسی عمومی (Public) یا محدود شده (در کد میدلوری مشخص نشده اما احتمالا نیاز به توکن دارد).
- نیاز به ارسال `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>branch</td><td>integer</td><td>**(الزامی)** شناسه شعبه برای فیلتر کردن فاکتورها.</td></tr><tr><td>id</td><td>mixed</td><td>**(الزامی)** شناسه سند مورد نظر. رفتار این فیلد دوگانه است: - **Array/Object:** اگر آرایه باشد، به عنوان لیست `id`های جدول `factors` در نظر گرفته می‌شود.
- **Single Value:** اگر تک مقدار باشد، به عنوان **شماره سریال نمایشی** در نظر گرفته می‌شود و سیستم به طور خودکار `ReferenceExtension` را از آن کم می‌کند تا سریال دیتابیس (`serial`) را پیدا کند.

</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%B1%D9%81%D8%B1%D9%86%D8%B3-%28factor%29">1. **واکشی رفرنس (Factor):** اطلاعات پایه فاکتور با Join به جداول `operators` و `customers` دریافت می‌شود.
2. **بررسی قابلیت چاپ:**
    - اگر `print == 0` باشد، خطای "عدم قابلیت چاپ" برمی‌گرداند.
    - اگر `status == 5` باشد، خطای وضعیت همراه با توضیحات فاکتور برمی‌گرداند.
3. **تعیین حالت نمایش (Print Mode):**
    - `1`: مشاهده بدون قیمت.
    - `2`: مشاهده با قیمت.
    - `3`: عدم مشاهده بلیت و واچر (مسدود).
4. **پردازش آیتم‌ها (Factor Items):**
    - **بررسی وضعیت آیتم:** آیتم‌های `refund` همیشه بررسی می‌شوند، اما آیتم‌های `online` بر اساس فیلد JSON `Status` بررسی می‌شوند.
    - **استخراج مسافران:**
        - اگر سرویس هتل (`accommodation`) باشد، لیست `roommate` از JSON استخراج می‌شود.
        - اطلاعات کامل مسافر از `customers` واکشی می‌شود.
        - **کشینگ (Redis):** اطلاعات کشور (`countries`) برای هر مسافر در Redis کش می‌شود تا فشار بر دیتابیس کاهش یابد.
    - **استخراج تامین‌کننده:** اطلاعات `colleagues` با استفاده از Redis کش و بازیابی می‌شود.
    - **ساختاردهی خروجی:** آیتم‌ها بر اساس نوع (`product`/`byproduct`) و شناسه مسافر گروه‌بندی می‌شوند. آیتم‌های استردادی (`refund`) به صورت تو در تو داخل آیتم اصلی قرار می‌گیرند.
5. **اطلاعات تماس (Branding):** اگر فیلد `colleague\_auth` مقدار داشته باشد، اطلاعات آژانس همکار (لوگو، آدرس، تلفن) جایگزین اطلاعات پیش‌فرض می‌شود.

</div>## Response Structure

**نکته مهم:** در کد فعلی، حتی در صورت موفقیت‌آمیز بودن عملیات و بازگشت دیتا، مقدار `status` برابر با `false` و کد `5008` برگردانده می‌شود (احتمالاً یک استاندارد داخلی یا لگاسی کد).

```json
{
  "status": false,  // ! توجه: طبق کد موجود فالس برمی‌گرداند
  "code": 5008,
  "data": [
    {
      "confirmation": 1,
      "serial_id": 100500,
      "track_code": "09-1200", // فرمت: ماه-سریال
      "print": {
        "id": 1,
        "title": { "fa": "مشاهده بدون قیمت", "en": "view without price" }
      },
      "internal": true,
      "contact_information": {
        "logo": "url...",
        "address": "Tehran...",
        "phone": "021..."
      },
      "operator": {
        "first_name": "Admin",
        "last_name": "User",
        "mobile": "0912..."
      },
      "leader": {
        "firstname_fa": "علی",
        "lastname_fa": "علوی",
        "mobile": "0912..."
      },
      "data": {
        // آرایه‌ای از آیتم‌ها گروه‌بندی شده بر اساس شناسه آیتم/مسافر
        "route_123": [
           {
             "serial_id": 50,
             "action": "route",
             "passenger": { ... }, // آبجکت کامل مسافر
             "sell": false,        // یا مبلغ اگر print=2 باشد
             "route": { ... }      // جزئیات پرواز
           }
        ]
      },
      "created": "2024-05-10 10:00:00"
    }
    // ممکن است شامل آبجکت‌های خطا هم باشد اگر یکی از فاکتورها مشکل داشته باشد
    // { "status": false, "code": 5006, "message": "..." }
  ]
}
```

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

<div class="api-docs" id="bkmrk-start-%E2%86%93-input-id-typ"><div class="flowchart"><div class="flow-item">Start</div><div class="flow-arrow">↓</div><div class="flow-item-decision">Input ID Type?</div><div style="display: flex; justify-content: space-between; width: 400px; margin: 0 auto;"><div style="width: 180px;"><div class="flow-arrow-label-left">Array</div><div class="flow-item-process">WhereIn('id', list)</div></div><div style="width: 180px;"><div class="flow-arrow-label-right">Single</div><div class="flow-item-process">Where('serial', input - Extension)</div></div></div><div class="flow-arrow">↓</div><div class="flow-item-process">Fetch Factors with Joins</div><div class="flow-arrow">↓</div><div style="border: 2px dashed #4caf50; padding: 15px; border-radius: 8px; margin: 10px 0;">**Loop Factors**<div class="flow-arrow">↓</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;">Return Error 5006/5001</div></div><div class="flow-arrow">↓ (Yes)</div><div class="flow-item-process">Determine Print Mode (1, 2, 3)</div><div class="flow-arrow">↓</div><div style="background-color: #e3f2fd; padding: 5px; border-radius: 4px;">**Process Items**  
- Check Item Status  
- Extract Passengers (Redis Cache)  
- Extract Suppliers (Redis Cache)  
- Handle Refunds</div><div class="flow-arrow">↓</div><div class="flow-item-process">Format Output &amp; Contact Info</div></div><div class="flow-arrow">↓</div><div class="flow-item-success">Return JSON (Code 5008)</div></div></div>