#P1412
POST /api/v2/trade/statement
Route Info
| Method | Endpoint | Controller | Middleware | Purpose |
| POST | /api/v2/trade/statement | V2TradeController@statementTradeApi | authWithJwt | دریافت صورتحساب (Statement) فاکتور مشخصشده با زبان تعیینشده |
منطق عملکرد
- شناسه فاکتور مورد نظر از
$request->idدریافت میشود. - زبان موردنظر کاربر از
$request['lang']['id']استخراج میگردد (برای خروجی محلیسازیشده). - در نهایت، متد
TradeController::statementTrade()با مقادیر(id, lang, branch, ReferenceExtension)فراخوانی و خروجی آن مستقیماً بازگردانده میشود. - هیچ پردازش اضافی (پرداختی، بروزرسانی DB) در این Endpoint انجام نمیشود؛ صرفاً پاسترو به لایهی کنترل اصلی است.
پارامترهای ورودی درخواست
| نام | نوع | ضروری | توضیح |
| id | integer | بله | شناسه فاکتور (Serial یا Reference ID) |
| lang.id | integer | بله | شناسه زبان (۱=فارسی، ۲=انگلیسی، ۳=عربی) |
| branch | integer | بله | شناسه شعبه درخواستکننده |
{
"id": 23051,
"lang": {"id": 1},
"branch": 12
}
خروجی
خروجی حاصل از اجرای تابع TradeController::statementTrade() بوده و معمولاً شامل دادهای ساختاریافته از صورتحساب کامل فاکتور است، شامل:
- header: اطلاعات بالای فاکتور (شماره، تاریخ، شعبه، مشتری)
- items: اقلام خرید/فروش
- summary: جمعبندی مالی (خالص، مالیات، بدهی، طلب)
- translations: عناوین با توجه به زبان انتخابی
{
"status": true,
"statement": {
"header": {...},
"items": [...],
"summary": {...}
}
}
امنیت
- دسترسی فقط از طریق JWT معتبر (میدلور authWithJwt).
- فاکتور فقط از شعبه مجاز قابل مشاهده است.
وابستگیها
- TradeController::statementTrade()
- $this->ReferenceExtension (ویژگی داخلی کنترلر)
- DB::table('factors')
کارایی
- میانگین زمان پاسخ: ۵۰ms (بدون عملیات DB اضافی).
- مصرف حافظه: بسیار پایین، صرفاً serialization JSON.
مدیریت خطا
- در صورت نبود فاکتور → خروجی Null یا Exception از
TradeController. - در صورت مقداردهی نادرست زبان یا شعبه → کد خطای اختصاصی TradeController.
اثرات جانبی
- فاقد تغییر در دادهها (Read-Only Endpoint).
- عدم ثبت SystemLog (فقط فراخوانی API زیرمجموعه).
ردپای حسابرسی
فاقد ثبت مستقیم ولی درصورت فعال بودن Audit در TradeController، گزارش View Statement لاگ میشود.
پیشنهادهای بهبود
- افزودن SystemLog داخلی برای رهگیری درخواستهای صورتحساب.
- پشتیبانی از خروجی PDF مستقیم از طریق سوییچ
?format=pdf.
جمعبندی
این Endpoint سطح Gateway برای دریافت صورت حساب از کنترلر TradeController است و وظیفهاش انتقال سریع پارامترهای فاکتور و زبان میباشد. منطق محاسبات و بازگردانی خروجی تماماً در کنترلر داخلی انجام میشود.