# POST /b2c/v1/online/{type}/lock

<div class="api-docs" id="bkmrk-">  <div class="endpoint-section">  
</div></div>## Lock Item (Pre-Booking)

این متد برای "قفل کردن" یا "اعتبارسنجی نهایی" یک آیتم انتخابی (مانند یک پرواز یا بلیط قطار) قبل از ورود اطلاعات مسافران استفاده می‌شود.   
در این مرحله، سیستم با تامین‌کننده ارتباط برقرار کرده، تغییرات احتمالی قیمت را بررسی می‌کند و یک رکورد در جدول رزروهای موقت ایجاد می‌کند.

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

  </div># Lock Selection

<div class="api-docs" id="bkmrk-url%3A-%2Fb2c%2Fv1%2Fonline%2F"><div class="endpoint-info"><div>**URL:** `/b2c/v1/online/{type}/lock`</div><div>**Method:** <span class="method-post">POST</span></div><div>**Controller:** V1OnlineController@lockItemProgress</div><div>**Auth:** <span style="color: red;">Required (JWT)</span></div><div>**Middleware:** `authWithJwt`</div></div></div>### Path Parameters

<div class="api-docs" id="bkmrk-parameter-type-descr"><table class="schema-table" dir="rtl"><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td dir="ltr">{type}</td><td>String</td><td>نوع سرویس (مثلاً `train`, `aircraft`, `hotel`). اگرچه در بدنه کنترلر مستقیماً استفاده نشده، اما برای تفکیک منطقی روت‌ها کاربرد دارد.</td></tr></tbody></table>

  </div>### Request Body Parameters

<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">data</td><td>Object/Array</td><td>Yes</td><td>آبجکت کامل آیتم انتخاب شده که از خروجی جستجو (Search) دریافت شده است. این داده عیناً برای اعتبارسنجی به سرویس ارسال می‌شود.</td></tr><tr><td dir="ltr">branch</td><td>Integer</td><td>No\*</td><td>شناسه شعبه. (معمولاً توسط میدل‌ور `authWithJwt` به درخواست تزریق می‌شود، اما اگر کلاینت ارسال کند اولویت دارد).</td></tr></tbody></table>

---

  </div>### Business Logic Details

#### ۱. احراز هویت و زمینه (Auth Context)

این متد توسط میدل‌ور `authWithJwt` محافظت می‌شود. این میدل‌ور اطلاعات کاربر (`operator`) و شعبه (`branch`) را به آبجکت `$request` تزریق می‌کند.

#### ۲. فراخوانی سرویس پایه (BaseService Call)

متد `BaseService::lockItemProgress` با پارامترهای زیر فراخوانی می‌شود:

<div class="api-docs" id="bkmrk-%24request-%3Edata%3A-%D8%A7%D8%B7%D9%84%D8%A7"><div class="logic-box" dir="rtl">- `$request->data`: اطلاعات آیتم انتخابی.
- `false`: پارامتر دوم (احتمالاً مربوط به force lock یا تنظیمات خاص که اینجا غیرفعال است).
- `$request->get('branch')`: زمینه شعبه برای قیمت‌گذاری.
- `1`: شناسه سیستمی یا نوع عامل (Hardcoded).

</div></div>#### ۳. ثبت در رزروهای موقت (Temporary Reservation)

نتیجه‌ی عملیات به همراه اطلاعات ورودی در جدول **`temporary_reservations`** ذخیره می‌شود:

<div class="api-docs" id="bkmrk-operator%3A-%D8%B4%D9%86%D8%A7%D8%B3%D9%87-%DA%A9%D8%A7%D8%B1%D8%A8"><div class="logic-box" dir="rtl">- **operator:** شناسه کاربر جاری (`$operator->id`).
- **data:** JSON ورودی (آنچه کاربر انتخاب کرده).
- **result:** JSON خروجی از سرویس (تاییدیه قفل و قیمت نهایی).

</div></div>شناسه این رکورد (`LockId`) تولید شده و در پاسخ بازگردانده می‌شود. این شناسه کلید اصلی برای مرحله بعد (ثبت مسافر و پرداخت) است.

#### ۴. مدیریت خطا (Exception Handling)

اگر سرویس خارجی خطا دهد یا آیتم موجود نباشد (Exception)، سیستم:

<div class="api-docs" id="bkmrk-%DA%A9%D8%AF-%D9%88%D8%B6%D8%B9%DB%8C%D8%AA-400-%28bad-re"><div class="logic-box" dir="rtl">- کد وضعیت **400 (Bad Request)** برمی‌گرداند.
- پیام خطا و Trace سیستم را در پاسخ قرار می‌دهد.
- اطلاعات تماس پشتیبانی (تلفن 021-91016838 و پنل Helpdesk) را به صورت خودکار به پاسخ اضافه می‌کند تا کلاینت بتواند به کاربر نمایش دهد.

</div>---

  </div>### Response Examples

#### مثال درخواست (Request)

```json
{
    "data": {
        "flight_id": "WS-5050",
        "provider_key": "some_encrypted_key_from_search_result",
        "price": 1500000,
        "class": "Economy"
    }
}
```

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

```json
{
    "status": true,
    "time": 1702123456,
    "lock_id": 9852,
    "data": {
        "status": "confirmed",
        "new_price": 1500000,
        "token": "reservation_token_12345",
        "expiration": "20 mins"
    }
}
```

**نکته:** مقدار `lock_id` (در این مثال 9852) باید توسط کلاینت ذخیره شده و در اندپوینت خرید (`trade/store`) ارسال شود.

#### پاسخ خطا (Error - 400 Bad Request)

```json
{
    "status": false,
    "time": 1702123499,
    "error": {
        "code": 1002,
        "message": "ظرفیت پرواز تکمیل شده است یا قیمت تغییر کرده است.",
        "trace": [ ... ]
    },
    "support": {
        "phone": "021-91016838 in 121",
        "email": "ict@airplus.app",
        "panel": "helpdesk.airplus.app"
    }
}
```