# POST /v2/core/hub/reservation

# Hub: Create Manual Wallet Transaction

این اندپوینت برای ثبت دستی یک تراکنش مالی (سند) در کیف پول (`wallet`) استفاده می‌شود. اگرچه URL به "رزرو" اشاره دارد، اما عملکرد اصلی آن ایجاد یک رکورد بدهکار (`debit`) یا بستانکار (`credit`) برای یک شعبه خاص است. این عملیات معمولاً توسط مدیران هاب برای اصلاح حساب یا ثبت سند دستی انجام می‌شود.

<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`</div><div>**Method:** <span class="method-post">POST</span></div><div>**Controller:** HubController@hubStoreReservation</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) دارد.
- شناسه اپراتور (`operator`) به صورت خودکار از توکن یا میدل‌ور استخراج می‌شود (`$request-&gt;get('operator')`).

</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>branch</td><td>integer/string</td><td>**(الزامی)** شناسه شعبه‌ای که تراکنش برای آن ثبت می‌شود. این مقدار هم در فیلد `branch` و هم در فیلد `object` ذخیره می‌گردد.</td></tr><tr><td>target\_type</td><td>string</td><td>نوع مقصد تراکنش (مثلاً `user`, `office`, `provider`).</td></tr><tr><td>target</td><td>integer/string</td><td>شناسه مقصد تراکنش (ID مربوط به `target_type`).</td></tr><tr><td>diagnosis</td><td>string</td><td>**(الزامی)** نوع ماهیت تراکنش. مقادیر مجاز: - `'credit'`: افزایش اعتبار (بستانکار)
- `'debit'`: کاهش اعتبار (بدهکار)

</td></tr><tr><td>value</td><td>numeric</td><td>**(الزامی)** مبلغ تراکنش. بسته به `diagnosis` در ستون `credit` یا `debit` قرار می‌گیرد.</td></tr><tr><td>description</td><td>string</td><td>توضیحات تراکنش (بابت چه چیزی).</td></tr></tbody></table>

</div>## Logic Details

فرآیند ثبت در کنترلر به صورت زیر است:

<div class="api-docs" id="bkmrk-%D8%A2%D9%85%D8%A7%D8%AF%D9%87%E2%80%8C%D8%B3%D8%A7%D8%B2%DB%8C-%D8%AF%D8%A7%D8%AF%D9%87%E2%80%8C%D9%87%D8%A7%3A-">1. **آماده‌سازی داده‌ها:**
    - فیلد `object_type` به صورت سخت‌کد شده برابر با `'branch'` قرار می‌گیرد.
    - فیلد `object` برابر با مقدار ارسالی `branch` تنظیم می‌شود.
    - شناسه اپراتور انجام‌دهنده عملیات از `$request->get('operator')->id` خوانده می‌شود.
2. **تعیین ماهیت مالی (Diagnosis Logic):**
    - اگر `diagnosis == 'credit'` باشد: مقدار `value` در ستون **credit** و ستون debit برابر 0 می‌شود.
    - اگر `diagnosis == 'debit'` باشد: مقدار `value` در ستون **debit** و ستون credit برابر 0 می‌شود.
3. **درج در دیتابیس:** آرایه ساخته شده مستقیماً با استفاده از `DB::table('wallet')->insert()` در جدول ذخیره می‌شود.

</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`
- در صورت بروز هرگونه Exception در فرآیند درج.

</div>```json
{
    "error": {
        "code": 1000,
        "message": "SQLSTATE[23000]: Integrity constraint violation..." // پیام خطا
    },
    "meta": {
        "timestamp": 1733737200
    }
}
```

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

<div class="api-docs" id="bkmrk-start-request-%28post%29"><div class="flowchart"><div class="flow-item">Start Request (POST)</div><div class="flow-arrow">↓</div><div class="flow-item-process">Extract Operator from Request Attributes</div><div class="flow-arrow">↓</div><div class="flow-item-decision">Check Diagnosis</div><div style="display: flex; justify-content: space-between; width: 300px; margin: 0 auto;"><div style="text-align: center;"><div class="flow-arrow">↓ (credit)</div><div class="flow-item-process" style="width: 120px; font-size: 12px;">Set Credit = Value  
Set Debit = 0</div></div><div style="text-align: center;"><div class="flow-arrow">↓ (debit)</div><div class="flow-item-process" style="width: 120px; font-size: 12px;">Set Debit = Value  
Set Credit = 0</div></div></div><div class="flow-arrow">↓</div><div class="flow-item-process">Prepare Insert Array  
(Set object_type='branch')</div><div class="flow-arrow">↓</div><div class="flow-item-process">DB::table('wallet')-&gt;insert(...)</div><div class="flow-arrow">↓</div><div class="flow-item-decision">Success?</div><div style="position: relative;"><div class="flow-arrow-label-left" style="top: -20px; left: -30px;">No</div><div class="flow-item-error" style="float: left; margin-left: -130px;">Return 400 Bad Request</div></div><div class="flow-arrow">↓ (Yes)</div><div class="flow-item-success">Return 201 Created</div></div></div>