Skip to main content
#P1744

PATCH /v2/core/hub/reservation/refund

Hub: Process Reservation Refund

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

Request Overview

URL: /v2/core/hub/reservation/refund
Method: PATCH
Controller: HubController@hubRefund
Middleware: authWithJwt

Access Control

  • نیاز به توکن احراز هویت (JWT) دارد.

Request Body Parameters

Field Type Description
id integer (الزامی) شناسه (ID) رزروی که باید استرداد شود.
value_type string (الزامی) نوع محاسبه جریمه. مقادیر مجاز:
  • 'percent': جریمه به صورت درصدی از مبلغ خرید (buy) رزرو محاسبه می‌شود.
  • مقادیر دیگر (مثلاً 'fixed'): جریمه به عنوان یک مبلغ ثابت در نظر گرفته می‌شود.
value numeric (الزامی) مقدار جریمه. اگر value_type برابر 'percent' باشد، این مقدار درصد است (مثلاً 10 برای ۱۰٪). در غیر این صورت، این مقدار مبلغ ریالی جریمه است.
description string (اختیاری) توضیحات اضافی که به انتهای توضیحات پیش‌فرض تراکنش کیف پول اضافه می‌شود.

Logic Details

فرآیند استرداد در کنترلر به صورت گام‌به‌گام زیر انجام می‌شود:

  1. یافتن رزرو:
    • سیستم با استفاده از id ارسال شده، در جدول hub_reservation جستجو می‌کند تا رکورد رزرو مورد نظر را پیدا کند.
  2. محاسبه جریمه (Penalty):
    • اگر value_type در درخواست برابر با 'percent' باشد، مبلغ جریمه از فرمول زیر محاسبه می‌شود:
      $penalty = ($reservation->buy * $request->value) / 100
    • در غیر این صورت، مقدار value ارسالی مستقیماً به عنوان مبلغ ثابت جریمه در نظر گرفته می‌شود.
  3. ایجاد تراکنش کیف پول (Wallet Transaction):
    • یک رکورد جدید برای درج در جدول wallet آماده می‌شود:
    • Mبلغ بستانکاری (credit): برابر است با مبلغ خرید اولیه رزرو منهای جریمه محاسبه‌شده ($reservation->buy - $penalty).
    • توضیحات (description): یک رشته توصیفی به صورت خودکار ساخته می‌شود که شامل شناسه رزرو، مبلغ جریمه، و توضیحات اختیاری ارسال شده در درخواست است.
    • این رکورد در جدول wallet درج می‌شود و اعتبار به حساب شعبه بازمی‌گردد.
  4. به‌روزرسانی وضعیت رزرو:
    • رکورد اصلی رزرو در جدول hub_reservation به‌روزرسانی می‌شود:
    • فیلد refund_penalty با مبلغ جریمه محاسبه‌شده پر می‌شود.
    • فیلد status به مقدار ثابت ۴ (به معنای استرداد شده) تغییر می‌کند.
    • فیلد updated_at با زمان فعلی به‌روز می‌شود.

Response Structure

پاسخ موفق

  • Status Code: 201 Created
  • Body: Empty (بدون محتوا).

پاسخ خطا

  • Status Code: 400 Bad Request
  • این خطا زمانی رخ می‌دهد که رزروی با id ارسال شده پیدا نشود.
{
    "error": {
        "code": 1000,
        "message": "رزرو یافت نشد."
    }
}

Flowchart

Start Request (PATCH /.../refund)
↓
Query `hub_reservation` by `id`
↓
Reservation Found?
No
Return 400 - "رزرو یافت نشد."
↓ (Yes)
Is `value_type` == 'percent'?
↓ (Yes)
Calculate Penalty:
`buy_price * value / 100`
↓ (No)
Set Penalty = `value` (fixed amount)
↓
Create `wallet` transaction (credit = buy_price - penalty)
↓
Update `hub_reservation` (status=4, refund_penalty=penalty)
↓
Return 201 Created (Empty Body)
Back to top