# POST /b2c/v1/trade/completion

<div class="api-docs" id="bkmrk-">  <div class="endpoint-section">  
</div></div>## Trade Completion &amp; Issuance

این اندپوینت برای **تکمیل فرآیند خرید** استفاده می‌شود.   
زمانی که پرداخت (آنلاین یا کیف پول) تایید شد، این متد برای صدور فاکتور (Factor)، بروزرسانی اطلاعات مسافران، ثبت تراکنش‌های مالی (Pledgers/Pays) و ارسال SMS نهایی به کاربر فراخوانی می‌گردد.

<div class="api-docs" id="bkmrk--1"><div class="endpoint-section">  
</div>  
---

  </div># Finalize Order

<div class="api-docs" id="bkmrk-url%3A-%2Fb2c%2Fv1%2Ftrade%2Fc"><div class="endpoint-info"><div>**URL:** `/b2c/v1/trade/completion`</div><div>**Method:** <span class="method-post">POST</span></div><div>**Controller:** V1TradeController@storeTradeAfterPay</div><div>**Middleware:** `authWithJwt` (Required)</div><div>**Transaction:** <span style="color: red;">Atomic (DB::transaction)</span></div></div>  </div>### Request Body Parameters

این متد یک آبجکت JSON پیچیده شامل اطلاعات پرداخت و جزئیات درخواست را دریافت می‌کند.

<div class="api-docs" id="bkmrk-parameter-type-requi"><table class="schema-table" dir="rtl"><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td dir="ltr">branch</td><td>Integer</td><td>Yes</td><td>شناسه شعبه (Branch ID) برای تعیین تنظیمات مالی و اعتباری.</td></tr><tr><td dir="ltr">payment</td><td>Object</td><td>Yes</td><td>اطلاعات مربوط به پرداخت انجام شده (مبلغ، درگاه و...).</td></tr><tr><td dir="ltr">request</td><td>Object</td><td>Yes</td><td>شامل جزئیات اصلی سفارش: - `passengers`: لیست کامل مسافران برای آپدیت در DB.
- `data`: لیست آیتم‌های خریداری شده (پرواز، هتل، قطار).
- `pledgers`: (اختیاری) لیست متعهدان مالی (برای B2B).
- `notices`: (بولین) آیا SMS ارسال شود؟
- `income_id`: شناسه درآمد.

</td></tr></tbody></table>

---

  </div>### Step-by-Step Logic Breakdown

#### ۱. ایجاد فاکتور (Factor Creation)

یک رکورد در جدول `factors` ایجاد می‌شود:

<div class="api-docs" id="bkmrk-serial%3A-%D8%AA%D9%88%D9%84%DB%8C%D8%AF-%D8%B3%D8%B1%DB%8C%D8%A7%D9%84-"><div class="logic-box" dir="rtl">- **Serial:** تولید سریال یکتا بر اساس شعبه.
- **Slug:** شناسه یکتای 8 کاراکتری برای پیگیری (Reference ID).
- **Status:** وضعیت پیش‌فرض `3` (صادر شده/موفق) تنظیم می‌شود.
- **Colleague Auth:** اگر کاربر B2B باشد، شناسه همکار ثبت می‌شود.

</div></div>#### ۲. مدیریت مسافران (Passengers Upsert)

سیستم روی آرایه `request['passengers']` حلقه می‌زند:

<div class="api-docs" id="bkmrk-%D8%A7%D8%B7%D9%84%D8%A7%D8%B9%D8%A7%D8%AA-%D9%87%D9%88%DB%8C%D8%AA%DB%8C-%28%D9%86%D8%A7%D9%85%D8%8C-"><div class="logic-box" dir="rtl">- اطلاعات هویتی (نام، نام خانوادگی، کد ملی، پاسپورت، تاریخ انقضا و...) در جدول `customers` **بروزرسانی (Update)** می‌شوند.
- تاریخ تولد و انقضای پاسپورت استانداردسازی می‌شود (حذف کاراکترهای اضافی).
- رابطه (Relationship) بین مسافر اصلی و همراهان تنظیم می‌شود.

</div></div>#### ۳. مدیریت مالی و تعهدات (Pledgers &amp; Pays)

این بخش مشخص می‌کند "چه کسی پول را می‌دهد":

<div class="api-docs" id="bkmrk-%D8%AD%D8%A7%D9%84%D8%AA-b2b-%28%D9%87%D9%85%DA%A9%D8%A7%D8%B1%29%3A-%D8%A7%DA%AF"><div class="logic-box" dir="rtl">- **حالت B2B (همکار):** اگر `pledgers` ارسال شده باشد، رکوردهایی در جدول `pledgers` و `pays` (نوع contract) ثبت می‌شود تا بدهی همکار مشخص شود.
- **حالت B2C (عادی):** اگر متعهدی نباشد، خودِ اپراتور/کاربر جاری به عنوان متعهد (type='operator') در نظر گرفته می‌شود.

</div></div>#### ۴. پردازش آیتم‌ها (Items Processing)

بر اساس نوع سرویس (`aircraft`, `train`, `accommodation`):

<div class="api-docs" id="bkmrk-aircraft%3A-%D9%88%D8%B6%D8%B9%DB%8C%D8%AA-%D8%A8%D9%84%DB%8C%D8%B7"><div class="logic-box" dir="rtl">- **Aircraft:** وضعیت بلیط بررسی شده، سن مسافر (برای تشخیص Infant) محاسبه می‌شود و آیتم در `factor_items` درج می‌شود.
- **Hub Reservation:** اگر سرویس از نوع `airplusHub` باشد، درخواست به جدول `hub_reservation` اضافه شده و مبلغ خرید به عنوان **Debit** (بدهی) در جدول `wallet` شعبه ثبت می‌شود.
- **Train/Hotel:** مشابه پرواز، اطلاعات رزرو پردازش و ذخیره می‌شوند.
- **Temporary Update:** وضعیت رزرو موقت (در جدول `temporary_reservations`) به تکمیل شده تغییر می‌کند.

</div></div>#### ۵. ارسال اعلان (Notification)

اگر `notices: true` باشد:

<div class="api-docs" id="bkmrk-%DB%8C%DA%A9-%D9%85%D8%AA%D9%86-%D9%BE%DB%8C%D8%A7%D9%85%DA%A9-%28magic-"><div class="logic-box" dir="rtl">- یک متن پیامک (Magic Text) به صورت تصادفی انتخاب می‌شود (مثلاً: "سفری هیجان انگیز").
- لینک فاکتور (`/f/{slug}`) تولید می‌شود.
- جاب `SendNotification` به صف `fastJob` ارسال می‌شود.
- لاگ سیستمی در `snailJob` ثبت می‌گردد.

</div>---

  </div>### Response Examples

#### پاسخ موفق (Success - 200 OK)

```json
{
    "status": true,
    "time": 1702123456,
    "payment": {
        "amount": 15000000,
        "method": "wallet"
    },
    "reference_id": "8XKA9L2P", // شناسه فاکتور (Factor Slug)
    "details": false // یا آرایه‌ای از خطاها در صورت وجود مشکل جزئی
}
```

#### پاسخ موفق همراه با هشدار (Success with Warnings)

اگر خرید کلی انجام شود اما برخی آیتم‌ها (مثلاً یکی از پروازها) رزرو نشوند:

```json
{
    "status": true,
    "time": 1702123456,
    "reference_id": "8XKA9L2P",
    "details": [
        {
            "local_id": 101,
            "message": "ظرفیت این کلاس پروازی تکمیل شده است."
        }
    ]
}
```

#### پاسخ خطا (Failure)

```json
{
    "status": false,
    "code": "1004-500",
    "message": "1004-500 : خطای داخلی سرور در هنگام ثبت رکورد",
    "trace": "..."
}
```