Skip to main content
#P1736

POST /v2/invoice/process

Hub: Create Payment Invoice

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

Request Overview

URL: /v2/invoice/process
Method: POST
Controller: HubController@createInvoice
Middleware: authWithJwt

Access Control

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

Body Parameters

Field Type Description
price integer (الزامی) مبلغ کل صورت‌حساب به ریال. حداقل مبلغ مجاز 10,000 ریال است.
type string (الزامی) نوع پرداخت. در حال حاضر فقط مقدار 'credit' پشتیبانی می‌شود.
id integer (الزامی) شناسه آبجکتی که این پرداخت به آن مرتبط است (مثلاً شناسه یک رزرو یا سفارش).
driver string (اختیاری) نام درایور درگاه پرداخت خاص (مانند 'zarinpal' یا 'behpardakht'). اگر ارسال نشود، درگاه پیش‌فرض شعبه انتخاب می‌شود.
return_url string (اختیاری) آدرسی که کاربر پس از اتمام عملیات پرداخت به آن هدایت می‌شود.
operator object (تزریق سیستمی) آبجکت اپراتور لاگین شده که توسط میدل‌ور به درخواست اضافه می‌شود.
branch integer (تزریق سیستمی) شناسه شعبه‌ای که اپراتور به آن تعلق دارد.

Logic Details

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

  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 به همراه مبلغ در قالب یک پاسخ موفقیت‌آمیز به کلاینت بازگردانده می‌شود.

Response Structure

پاسخ موفق

  • Status Code: 201 Created
  • Body: یک آبجکت حاوی لینک پرداخت نهایی.
{
    "payload": {
        "status": "payment_link",
        "amount": 50000,
        "url": "https://ipg.airplus.app/invoice/payment/aB3xZ7cR"
    },
    "meta": {
        "timestamp": 1715001200
    }
}

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

  • 422 Unprocessable Entity: خطای اعتبارسنجی ورودی‌ها (مانند عدم ارسال فیلدها یا مبلغ کم).
  • 400 Bad Request: نوع پرداخت نامعتبر است یا هیچ درگاه پرداخت فعالی برای شعبه یافت نشده است.
{
  "error": {
    "code": 1000,
    "message": "درگاه پرداخت فعال یافت نشد"
  }
}

Flowchart

Start Request
↓
Validate Inputs (price, type, id)
↓
Inputs Valid & price >= 10k?
No
Error: 422
↓ (Yes)
type == 'credit'?
No
Error: 400 Invalid Type
↓ (Yes)
Create record in `airplus_bills` table
↓
Get Gateway Config
1. Check for `driver` input
2. Fallback to branch default
↓
Gateway Found?
No
Error: 400 No Gateway
↓ (Yes)
Generate Unique Slug
(Loop until unique in `airplus_invoices`)
↓
Finalize Invoice
1. Insert into `airplus_invoices`
2. Link to Bill & Gateway
↓
Construct Payment URL
↓
Return 201 Created with URL
Back to top