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

# Hub: Undo Reservation Refund

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

<div class="api-docs" id="bkmrk-"></div>## Request Overview

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fcore%2Fhub%2Fre"><div class="endpoint-info"><div>**URL:** `/v2/core/hub/reservation/refund/undo`</div><div>**Method:** <span class="method-patch">PATCH</span></div><div>**Controller:** HubController@hubUndoRefund</div><div>**Middleware:** authWithJwt</div></div></div>## Access Control

<div class="api-docs" id="bkmrk-%D9%86%DB%8C%D8%A7%D8%B2-%D8%A8%D9%87-%D8%AA%D9%88%DA%A9%D9%86-%D8%A7%D8%AD%D8%B1%D8%A7%D8%B2-%D9%87">- نیاز به توکن احراز هویت (JWT) دارد.
- شناسه شعبه (`branch`) به صورت خودکار از درخواست (احتمالاً توسط میدلور) استخراج شده و برای بررسی موجودی استفاده می‌شود.

</div>## Request Body Parameters

<div class="api-docs" id="bkmrk-field-type-descripti"><table class="schema-table" dir="rtl"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>integer</td><td>**(الزامی)** شناسه (ID) رزروی که عملیات استرداد آن باید لغو شود. سیستم از این شناسه برای یافتن تراکنش استرداد مرتبط در جدول `wallet` استفاده می‌کند.</td></tr></tbody></table>

</div>## Logic Details

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

<div class="api-docs" id="bkmrk-%DB%8C%D8%A7%D9%81%D8%AA%D9%86-%D8%AA%D8%B1%D8%A7%DA%A9%D9%86%D8%B4-%D8%A7%D8%B3%D8%AA%D8%B1%D8%AF%D8%A7%D8%AF">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` به‌روز می‌شود.

</div>## Response Structure

### پاسخ موفق

<div class="api-docs" id="bkmrk-status-code%3A-201-cre">- **Status Code:** `201 Created`
- **Body:** Empty (بدون محتوا).

</div>### پاسخ‌های خطا

<div class="api-docs" id="bkmrk-status-code%3A-400-bad">- **Status Code:** `400 Bad Request`
- این خطا در سه حالت ممکن است رخ دهد:

</div>**۱. تراکنش استرداد یافت نشد:**

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

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

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

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

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

<div class="api-docs" id="bkmrk--1"></div>## Flowchart

<div class="api-docs" id="bkmrk-start-request-%28patch"><div class="flowchart"><div class="flow-item">Start Request (PATCH /.../refund/undo)</div><div class="flow-arrow">↓</div><div class="flow-item-process">Find Refund Transaction in `wallet` table</div><div class="flow-arrow">↓</div><div class="flow-item-decision">Transaction Found?</div><div style="position: relative;"><div class="flow-arrow-label-left">No</div><div class="flow-item-error" style="float: left; margin-left: -150px;">Return 400 - "استرداد یافت نشد"</div></div><div class="flow-arrow">↓ (Yes)</div><div class="flow-item-decision">Check Wallet Balance (getCheckWallet)</div><div style="position: relative;"><div class="flow-arrow-label-left">No (Insufficient)</div><div class="flow-item-error" style="float: left; margin-left: -150px;">Return 400 - "موجودی ناکافی"</div></div><div class="flow-arrow">↓ (Yes)</div><div class="flow-item-process">Create Reversal `Debit` Transaction in `wallet`</div><div class="flow-arrow">↓</div><div class="flow-item-process">Update `hub_reservation` (status=1, refund_penalty=null)</div><div class="flow-arrow">↓</div><div class="flow-item-success">Return 201 Created</div></div></div>