# POST /v2/invoice/process

# Hub: Create Payment Invoice

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

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

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Finvoice%2Fpro"><div class="endpoint-info"><div>**URL:** `/v2/invoice/process`</div><div>**Method:** <span class="method-post">POST</span></div><div>**Controller:** HubController@createInvoice</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>## 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>price</td><td>integer</td><td>**(الزامی)** مبلغ کل صورت‌حساب به ریال. حداقل مبلغ مجاز **10,000** ریال است.</td></tr><tr><td>type</td><td>string</td><td>**(الزامی)** نوع پرداخت. در حال حاضر فقط مقدار `'credit'` پشتیبانی می‌شود.</td></tr><tr><td>id</td><td>integer</td><td>**(الزامی)** شناسه آبجکتی که این پرداخت به آن مرتبط است (مثلاً شناسه یک رزرو یا سفارش).</td></tr><tr><td>driver</td><td>string</td><td>**(اختیاری)** نام درایور درگاه پرداخت خاص (مانند `'zarinpal'` یا `'behpardakht'`). اگر ارسال نشود، درگاه پیش‌فرض شعبه انتخاب می‌شود.</td></tr><tr><td>return\_url</td><td>string</td><td>**(اختیاری)** آدرسی که کاربر پس از اتمام عملیات پرداخت به آن هدایت می‌شود.</td></tr><tr><td>operator</td><td>object</td><td>**(تزریق سیستمی)** آبجکت اپراتور لاگین شده که توسط میدل‌ور به درخواست اضافه می‌شود.</td></tr><tr><td>branch</td><td>integer</td><td>**(تزریق سیستمی)** شناسه شعبه‌ای که اپراتور به آن تعلق دارد.</td></tr></tbody></table>

</div>## Logic Details

فرآیند ایجاد لینک پرداخت دارای چندین مرحله کلیدی است:

<div class="api-docs" id="bkmrk-%D8%A7%D8%B9%D8%AA%D8%A8%D8%A7%D8%B1%D8%B3%D9%86%D8%AC%DB%8C-%D8%A7%D9%88%D9%84%DB%8C%D9%87%3A-%D8%A8%D8%B1">1. **اعتبارسنجی اولیه:**
    - بررسی می‌شود که فیلدهای الزامی `price`, `type`, و `id` در درخواست وجود داشته باشند.
    - مبلغ `price` باید بزرگتر یا مساوی **10,000 ریال** باشد.
    - نوع پرداخت (`type`) باید دقیقاً برابر با `'credit'` باشد. در غیر این صورت خطا بازگردانده می‌شود.
2. **ثبت رکورد قبض (Bill):**
    - یک رکورد جدید در جدول `airplus_bills` ایجاد می‌شود.
    - این رکورد حاوی اطلاعات پایه پرداخت مانند مبلغ، شناسه اپراتور، شعبه و شناسه آبجکت مرتبط است. وضعیت اولیه آن `1` (فعال) ثبت می‌شود.
3. **انتخاب درگاه پرداخت (Gateway Selection):**
    - تابع کمکی `Functions::getGatewayConfig` فراخوانی می‌شود.
    - **اولویت اول:** اگر فیلد `driver` در درخواست ارسال شده باشد، سیستم به دنبال یک درگاه فعال با همان نام درایور برای آن شعبه می‌گردد.
    - **اولویت دوم (Fallback):** اگر `driver` ارسال نشده باشد، سیستم از جدول `office_config` به دنبال درگاه پیش‌فرض (`DEFAULT\_BANKING\_GATEWAY`) برای آن شعبه می‌گردد.
    - اگر هیچ درگاه فعالی (نه با درایور مشخص و نه به عنوان پیش‌فرض) یافت نشود، خطا بازگردانده می‌شود.
4. **ایجاد فاکتور نهایی (Invoice):**
    - با استفاده از تابع `Functions::generateSlugUnique`، یک رشته تصادفی و **منحصر به فرد** به طول ۸ کاراکتر به عنوان `slug` فاکتور تولید می‌شود. این تابع تضمین می‌کند که اسلاگ در جدول `airplus_invoices` تکراری نباشد.
    - یک رکورد جدید در جدول `airplus_invoices` ثبت می‌شود که حاوی اسلاگ، اطلاعات درگاه، مبلغ، و شناسه قبض (Bill) ایجاد شده در مرحله ۲ است.
5. **تولید لینک و ارسال پاسخ:**
    - یک URL پرداخت با استفاده از دامنه ثابت `https://ipg.airplus.app/invoice/payment/` و اسلاگ منحصر به فرد تولید می‌شود.
    - این URL به همراه مبلغ در قالب یک پاسخ موفقیت‌آمیز به کلاینت بازگردانده می‌شود.

</div>## Response Structure

### پاسخ موفق

<div class="api-docs" id="bkmrk-status-code%3A-201-cre">- **Status Code:** `201 Created`
- **Body:** یک آبجکت حاوی لینک پرداخت نهایی.

</div>```json
{
    "payload": {
        "status": "payment_link",
        "amount": 50000,
        "url": "https://ipg.airplus.app/invoice/payment/aB3xZ7cR"
    },
    "meta": {
        "timestamp": 1715001200
    }
}
```

### پاسخ‌های خطا (نمونه)

<div class="api-docs" id="bkmrk-422-unprocessable-en">- `422 Unprocessable Entity`: خطای اعتبارسنجی ورودی‌ها (مانند عدم ارسال فیلدها یا مبلغ کم).
- `400 Bad Request`: نوع پرداخت نامعتبر است یا هیچ درگاه پرداخت فعالی برای شعبه یافت نشده است.

</div>```json
{
  "error": {
    "code": 1000,
    "message": "درگاه پرداخت فعال یافت نشد"
  }
}
```

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

<div class="api-docs" id="bkmrk-start-request-%E2%86%93-vali"><div class="flowchart"><div class="flow-item">Start Request</div><div class="flow-arrow">↓</div><div class="flow-item-process">Validate Inputs (price, type, id)</div><div class="flow-arrow">↓</div><div class="flow-item-decision">Inputs Valid &amp; price &gt;= 10k?</div><div style="position: relative;"><div class="flow-arrow-label-right" style="top: -20px; right: -50px;">No</div><div class="flow-item-error" style="float: right; margin-right: -140px; width: 120px;">Error: 422</div></div><div class="flow-arrow">↓ (Yes)</div><div class="flow-item-decision">type == 'credit'?</div><div style="position: relative;"><div class="flow-arrow-label-right" style="top: -20px; right: -50px;">No</div><div class="flow-item-error" style="float: right; margin-right: -140px; width: 120px;">Error: 400 Invalid Type</div></div><div class="flow-arrow">↓ (Yes)</div><div class="flow-item-process" style="background-color: #e8f5e9;">Create record in `airplus_bills` table</div><div class="flow-arrow">↓</div><div class="flow-item-process" style="background-color: #fff3e0;">**Get Gateway Config**  
1. Check for `driver` input  
2. Fallback to branch default</div><div class="flow-arrow">↓</div><div class="flow-item-decision">Gateway Found?</div><div style="position: relative;"><div class="flow-arrow-label-right" style="top: -20px; right: -50px;">No</div><div class="flow-item-error" style="float: right; margin-right: -140px; width: 120px;">Error: 400 No Gateway</div></div><div class="flow-arrow">↓ (Yes)</div><div class="flow-item-process">**Generate Unique Slug**  
(Loop until unique in `airplus_invoices`)</div><div class="flow-arrow">↓</div><div class="flow-item-process" style="background-color: #e8f5e9;">**Finalize Invoice**  
1. Insert into `airplus_invoices`  
2. Link to Bill &amp; Gateway</div><div class="flow-arrow">↓</div><div class="flow-item-process">Construct Payment URL</div><div class="flow-arrow">↓</div><div class="flow-item-success">Return 201 Created with URL</div></div></div>