#P1400

POST /api/v2/trade/store

Route Info

Method	Endpoint	Controller	Middleware	Purpose
POST	/api/v2/trade/store	V2TradeController@storeTrade	authWithJwt	ثبت تراکنش خرید/رزرو با جزئیات مسافران، آیتم‌ها، پرداخت و نوتیفیکیشن

منطق عملکرد

شروع تراکنش دیتابیس DB::transaction برای اتمیک بودن کل فرآیند.
دریافت داده‌های فاکتور اصلی و تولید serial یونیک با StaticController::getSerialId.
ثبت یا به‌روزرسانی اطلاعات مسافران در جدول customers با اعتبارسنجی مدارک.
پردازش آرایه آیتم‌ها (data[]) بر مبنای نوع (هواپیما، قطار، هتل، اقامتگاه، بیمه، خدمات...).
در حالت رزرو آنلاین: اتصال به سرویس تأمین‌کننده، تأیید lock و book، ذخیره جزئیات در factor_items.
در صورت شرایط خاص: درج داده‌های هاب در hub_reservation و محاسبه کارمزدها.
ثبت پرداخت‌ها در جدول pays، بروزرسانی بدهکاری/بستانکاری در wallet.
ارسال نوتیفیکیشن شخصی‌سازی شده با متن و برند شعبه.
در صورت خطا: توقف تراکنش و گزارش به Visa::AddSystemReport.

ورودی‌ها

فیلد	نوع داده	ضروری	توضیح
branch	int	بله	شناسه شعبه ثبت‌کننده
operator	object	بله	اطلاعات کاربر اپراتور (دارای id و نام)
passengers	array	بله	لیست مسافران همراه با جزئیات کامل
data	array	بله	لیست آیتم‌های خرید/رزرو
income_id	int	خیر	شناسه مرجع درآمد
print	bool	خیر	چاپ خودکار فاکتور
notices	bool	خیر	ارسال نوتیفیکیشن

{
  "branch": 12,
  "operator": { "id": 5, "name": "Operator A" },
  "passengers": [ { "id": 1, "name_fa": "علی رضایی", "phone_number": "0912..." } ],
  "data": [ { "action": "online", "type": "aircraft", "buy": "2500000", "sell": "3000000" } ],
  "notices": true
}

خروجی

فیلد	نوع	شرح
status	bool	نتیجه عملیات
time	int	زمان ثبت
details	array\|bool	مشکلات احتمالی یا false
code	string	کد خطا (در حالت ناموفق)
message	string	پیام یا توضیح خطا

{
  "status": true,
  "time": 1732021035,
  "details": false
}

امنیت

تأیید هویت از طریق authWithJwt.
ولیدیشن برای passengers و تاریخ‌ها.
بررسی type و کنترل سرویس‌دهنده برای جلوگیری از داده مخرب.
گزارش خطاها به سامانه مرکزی Visa::AddSystemReport.

کارایی

استفاده از تراکنش دیتابیس برای جلوگیری از نیمه‌کاره ماندن داده‌ها.
بهینه‌سازی درج دسته‌ای برای wallet و hub_reservation.
احتمال کندی در حلقه‌های پردازش آیتم‌های رزرو آنلاین؛ پیشنهاد بهبود با Queue.

وابستگی‌ها

use DB;
use Carbon\Carbon;
use App\\Models\\Customer;
use App\\Helpers\\Functions;
use App\\Http\\Controllers\\StaticController;
use Morilog\\Jalali\\Jalalian;
use Visa;

کدهای خطا

کد	شرح	منبع
1001	درخواست نامعتبر یا داده ناقص	storeTrade
1004-{ExceptionCode}	خطا در اجرای تراکنش	Exception Handler

جمع‌بندی

این Endpoint قلب عملیات فروش/رزرو است. نیازمند اعتبارسنجی دقیق، عملکرد سریع و گزارش‌گیری جامع می‌باشد. با پیاده‌سازی پیشنهادها، می‌توان ریسک خطا و فشار پردازشی را به‌طور قابل‌توجهی کاهش داد.