Skip to main content
#P1794

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


Lock Item (Pre-Booking)

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



Lock Selection

URL: /b2c/v1/online/{type}/lock
Method: POST
Controller: V1OnlineController@lockItemProgress
Auth: Required (JWT)
Middleware: authWithJwt

Path Parameters

Parameter Type Description
{type} String نوع سرویس (مثلاً train, aircraft, hotel). اگرچه در بدنه کنترلر مستقیماً استفاده نشده، اما برای تفکیک منطقی روت‌ها کاربرد دارد.

Request Body Parameters

Parameter Type Required Description
data Object/Array Yes آبجکت کامل آیتم انتخاب شده که از خروجی جستجو (Search) دریافت شده است. این داده عیناً برای اعتبارسنجی به سرویس ارسال می‌شود.
branch Integer No* شناسه شعبه. (معمولاً توسط میدل‌ور authWithJwt به درخواست تزریق می‌شود، اما اگر کلاینت ارسال کند اولویت دارد).

Business Logic Details

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

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

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

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

  • $request->data: اطلاعات آیتم انتخابی.
  • false: پارامتر دوم (احتمالاً مربوط به force lock یا تنظیمات خاص که اینجا غیرفعال است).
  • $request->get('branch'): زمینه شعبه برای قیمت‌گذاری.
  • 1: شناسه سیستمی یا نوع عامل (Hardcoded).

۳. ثبت در رزروهای موقت (Temporary Reservation)

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

  • operator: شناسه کاربر جاری ($operator->id).
  • data: JSON ورودی (آنچه کاربر انتخاب کرده).
  • result: JSON خروجی از سرویس (تاییدیه قفل و قیمت نهایی).

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

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

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

  • کد وضعیت 400 (Bad Request) برمی‌گرداند.
  • پیام خطا و Trace سیستم را در پاسخ قرار می‌دهد.
  • اطلاعات تماس پشتیبانی (تلفن 021-91016838 و پنل Helpdesk) را به صورت خودکار به پاسخ اضافه می‌کند تا کلاینت بتواند به کاربر نمایش دهد.

Response Examples

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

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

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

{
    "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)

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