#P1416
POST /api/v2/trade/payment-receipt
Route Info
| Method | Endpoint | Controller | Middleware | Purpose |
| POST | /api/v2/trade/payment-receipt | V2TradeController@paymentReceiptTradeApi | authWithJwt | دریافت و تولید رسید پرداخت (Payment Receipt) فاکتور مربوطه |
منطق عملکرد
- شناسه زبان از
$request['lang']['id']و شناسه فاکتور از$request->idدریافت میشود. - پارامترهای لازم برای تولید رسید شامل:
- فاکتور (id)
- زبان رابط (lang)
- شناسه شعبه (branch)
- مقدار داخلی
$this->ReferenceExtension
TradeController::paymentReceiptTrade()پاس داده میشوند. - متد
TradeController::paymentReceiptTrade()خروجی رسید نهایی را بهصورت داده ساختیافته بازمیگرداند.
پارامترهای ورودی
| نام | نوع | ضروری | توضیح |
| id | integer | بله | شناسه فاکتور (reference) |
| lang.id | integer | بله | شناسه زبان خروجی (۱=فارسی،۲=انگلیسی،۳=عربی) |
| branch | integer | بله | کد شعبه درخواستکننده |
{
"id": 13725,
"lang": {"id": 1},
"branch": 12
}
ساختار خروجی
پاسخ تابع TradeController::paymentReceiptTrade() بهصورت JSON بازگردانده میشود. ساختار معمول شامل:
- status: موفق / ناموفق
- receipt: جزئیات پرداخت و مشخصات فاکتور
- customer: اطلاعات پرداختکننده / خریدار
- details: مقادیر مربوط به مبالغ، شماره فاکتور، تاریخ، ارجاع و سریال
{
"status": true,
"receipt": {
"factor_id": 13725,
"serial": "F-2025-1105",
"branch": "اصفهان مرکزی",
"amount": 12800000,
"currency": "IRR",
"datetime": "2025-11-19 14:31",
"payment_type": "wallet"
},
"customer": {...}
}
امنیت
- تحت کنترل
authWithJwt. - فقط اپراتورهایی که به فاکتور مربوطه دسترسی دارند میتوانند رسید را مشاهده کنند.
- کد مرجع داخلی
ReferenceExtensionبرای ایمنی عددی در IDها اعمال میشود.
وابستگیها
- TradeController::paymentReceiptTrade()
- فیلدهای پنهان داخلی ReferenceExtension
- جدول factors و pays
کارایی
- میانگین سرعت پاسخ: ~45ms (کاملاً ایستا، بدون تراکنش سنگین).
- فقط فرایند خوانش، بدون تغییر در پایگاهداده.
مدیریت خطا
- در صورت نامعتبر بودن ID → خروجی Null یا خطای مدیریتشده در TradeController.
- در صورت فقدان زبان یا branch → خطای پارامتر ناقص.
اثرات جانبی
فاقد اثرات جانبی. فقط خروجی نمایشی و هیچ دادهای در DB تغییر نمیکند.
ردپای حسابرسی
در این متد SystemLog ثبت نمیشود اما در سطح زیرین TradeController ممکن است عملیات مشاهدهی رسید ثبت شود.
پیشنهادهای بهبود
- افزودن قابلیت خروجی PDF رسید.
- اطمینان از ذخیره رویداد “ViewReceipt” در SystemLog برای رهگیری دقیقتر.
جمعبندی
این Endpoint یک Gateway سبک برای تولید رسید پرداخت فاکتور است که منطق اصلی نمایش و فرمت داده را از TradeController ارث میبرد. بدون منطق تجاری سنگین، فقط دادهی نهایی را برمیگرداند.