Skip to main content
#P1745

PATCH /v2/core/hub/reservation/refund/undo

Hub: Undo Reservation Refund

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

Request Overview

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

Access Control

  • نیاز به توکن احراز هویت (JWT) دارد.
  • شناسه شعبه (`branch`) به صورت خودکار از درخواست (احتمالاً توسط میدلور) استخراج شده و برای بررسی موجودی استفاده می‌شود.

Request Body Parameters

Field Type Description
id integer (الزامی) شناسه (ID) رزروی که عملیات استرداد آن باید لغو شود. سیستم از این شناسه برای یافتن تراکنش استرداد مرتبط در جدول wallet استفاده می‌کند.

Logic Details

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

  1. یافتن تراکنش استرداد:
    • سیستم در جدول wallet به دنبال تراکنشی می‌گردد که شرایط زیر را داشته باشد:
      • target_type == 'refund'
      • target == request('id') (شناسه رزرو)
      • credit > 0 (تراکنش بستانکاری که پول را به شعبه بازگردانده است)
    • اگر چنین تراکنشی یافت نشود، خطای 400 با پیام "استرداد یافت نشد" بازگردانده می‌شود.
  2. بررسی موجودی کیف پول (Critical Step):
    • قبل از برداشت وجه، سیستم با فراخوانی متد AccountingController::getCheckWallet موجودی شعبه را بررسی می‌کند.
    • این متد چک می‌کند که آیا موجودی فعلی شعبه (با در نظر گرفتن حد اعتبار یا credit_limit) برای پوشش مبلغ استرداد شده ($transaction->credit) کافی است یا خیر.
    • اگر موجودی کافی نباشد، خطای 400 با پیام "موجودی کیف پول جهت برگشت این آیتم کافی نیست" بازگردانده می‌شود.
  3. ایجاد تراکنش بدهکاری (Debit Transaction):
    • یک رکورد جدید در جدول wallet برای برداشت مبلغ استرداد شده از حساب شعبه ایجاد می‌شود:
    • Mبلغ بدهکاری (debit): برابر است با مبلغ credit تراکنش استرداد اولیه.
    • توضیحات (description): متنی مانند "برگشت استرداد [شناسه تراکنش]" ثبت می‌شود.
    • این رکورد بدهکاری، تراکنش بستانکاری قبلی را خنثی می‌کند.
  4. بازگردانی وضعیت رزرو:
    • رکورد اصلی رزرو در جدول hub_reservation به‌روزرسانی می‌شود:
    • فیلد refund_penalty به null تغییر می‌کند.
    • فیلد status به مقدار ۱ (به معنای فعال/صادر شده) بازمی‌گردد.
    • فیلد updated_at به‌روز می‌شود.

Response Structure

پاسخ موفق

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

پاسخ‌های خطا

  • Status Code: 400 Bad Request
  • این خطا در سه حالت ممکن است رخ دهد:

۱. تراکنش استرداد یافت نشد:

{
    "error": {
        "code": 1000,
        "message": "استرداد یافت نشد"
    }
}

۲. موجودی کیف پول ناکافی است:

{
    "error": {
        "code": 1000,
        "message": "موجودی کیف پول جهت برگشت این آیتم کافی نیست."
    },
    "meta": {
        "timestamp": 1733737200
    }
}

۳. بروز خطای عمومی (Exception):

{
    "error": {
        "code": 1000,
        "message": "General exception message..."
    },
    "meta": {
        "timestamp": 1733737200
    }
}

Flowchart

Start Request (PATCH /.../refund/undo)
↓
Find Refund Transaction in `wallet` table
↓
Transaction Found?
No
Return 400 - "استرداد یافت نشد"
↓ (Yes)
Check Wallet Balance (getCheckWallet)
No (Insufficient)
Return 400 - "موجودی ناکافی"
↓ (Yes)
Create Reversal `Debit` Transaction in `wallet`
↓
Update `hub_reservation` (status=1, refund_penalty=null)
↓
Return 201 Created
Back to top