#P1511
POST /gateway/invoice/{drive}
Route Info
| Method | Endpoint | Controller | Middleware | Purpose |
| POST | /api/v2/gateway/invoice/{drive} | V2CreditDebitController@gatewayInvoice | authWithJwt | تولید لینک پرداخت آنلاین از طریق درگاه متصلشده به شناسه یا مدل موردنظر (drive). |
منطق عملکرد تابع
تابع gatewayInvoice برای تولید فاکتور پرداخت اینترنتی طراحی شده است. پارامتر {drive} شناسهٔ آبجکت (مثلاً پرداخت، سفارش یا اعلان مالی) موردنظر را مشخص میکند. سیستم نوع مدل را بررسی کرده، مبلغ و اطلاعات حساب مرتبط را از پایگاه داده واکشی مینماید و پس از محاسبهٔ پارامترهای امنیتی، یک لینک سفارش فعال در جدول payment_gateway ایجاد میکند.
در نهایت، خروجی شامل URL پرداخت و شناسه تراکنش است که کاربر سمت کلاینت یا موبایل میتواند برای پرداخت در مرورگر یا اپلیکیشن بانک استفاده کند.
ورودیها
| نام پارامتر | نوع | منبع | الزامی | توضیح |
| drive | integer | URL Param | بله | شناسهٔ آیتم پرداخت یا اعلان. |
| amount | integer | Body | خیر | مبلغ نهایی، فقط اگر نیاز به override داشته باشد. |
| callback_url | string | Body | خیر | آدرس بازگشت کاربر پس از پرداخت (در صورت عدم ارسال از config خوانده میشود). |
| currency | string | Body | خیر | واحد ارزی (پیشفرض IRR). |
خروجی (Response)
{
"status": true,
"gateway": "zarinpal",
"invoice": {
"id": 114,
"amount": 250000,
"currency": "IRR",
"reference": "A1Z4R36P",
"callback_url": "https://example.com/callback/zp",
"link": "https://gateway.zarinpal.com/pg/StartPay/A1Z4R36P",
"expire_in": 900
}
}
نکات امنیتی
- توکن JWT الزامی است.
- کنترل مالکیت داده: سیستم بررسی میکند کاربر یا شعبهی فعلی مجاز به دیدن یا پرداخت آن آیتم هست.
- پارامتر مبلغ رمزگذاری و در سمت درگاه تأیید مجدد میشود.
نکات عملکردی
- عملیات ثبت و لینکسازی کمتر از ۱۰۰ms انجام میشود.
- در صورت وجود لینک فعال قبلی برای همان drive، سیستم از لینک موجود استفاده میکند (prevent duplicate).
- درگاه پرداخت از تنظیمات فعال Redis انتخاب میگردد.
وابستگیها
- use Illuminate\Support\Facades\DB;
- use App\Helpers\Functions;
- use Morilog\Jalali\Jalalian;
- use App\Http\Controllers\Gateways\ZarinpalController;
کدهای خطا
| کد | شرح خطا | منبع |
| 400 | پارامتر یا دادهٔ درگاه نامعتبر است. | Validator |
| 403 | کاربر مجاز به تولید فاکتور این آیتم نیست. | Auth Middleware |
| 404 | آیتم مالی یافت نشد. | Query |
| 500 | خطای سرور هنگام برقراری ارتباط با درگاه پرداخت. | Exception |
پیشنهادهای امنیتی
- افزودن امضای دیجیتال به لینک خروجی برای جلوگیری از تغییر غیرمجاز.
- ثبت IP و User-Agent تولیدکننده لینک در لاگ.
پیشنهادهای بهبود
- پشتیبانی از gatewayهای چندگانه (zarinpal, nextpay, idpay) از طریق strategy pattern.
- افزودن پارامتر
metaجهت ارسال دادهٔ اضافی به callback.
ممیزی و لاگها
- نوع لاگ:
GatewayInvoice. - موارد ممیزی: شناسهٔ drive، مبلغ، درگاه انتخابی، IP کاربر.
- سطح حساسیت: Audit.
جمعبندی
تابع gatewayInvoice درگاه میانی سیستم مالی را مدیریت میکند و با تولید سریع لینک پرداخت، کاربران را از اتصال مستقیم به سرویس پرداخت بینیاز میسازد. این تابع یکی از اجزای کلیدی ماژول تراکنش آنلاین است که امنیت، سرعت و یکپارچگی داده را در سطح شعبه تضمین میکند.