Skip to main content
#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 قلب عملیات فروش/رزرو است. نیازمند اعتبارسنجی دقیق، عملکرد سریع و گزارش‌گیری جامع می‌باشد. با پیاده‌سازی پیشنهادها، می‌توان ریسک خطا و فشار پردازشی را به‌طور قابل‌توجهی کاهش داد.

Back to top