Skip to main content
#P1491

POST /pay/store

Route Info

Method Endpoint Controller Middleware Purpose
POST /api/v2/pay/store V2CreditDebitController@storePay authWithJwt ذخیره رکوردهای پرداخت (Pay) جدید همراه با اطلاعات حساب، طرف حساب و تراکنش مالی؛ بروزرسانی کش مالی در Redis.

منطق عملکرد تابع

تابع storePay برای ثبت گروهی تراکنش‌های پرداخت و دریافتی طراحی شده است. ابتدا داده درخواست ($request->data) پردازش و شناسه مالی سال جاری بر اساس تابع StaticController::getYearFinancial() محاسبه می‌شود. سپس رکوردها در جدول pays درج می‌گردند. در پایان، بر اساس نوع حساب (reference یا aggregation)، اطلاعات مالی حساب مربوطه از طریق TradeController::financial() بازخوانی شده و در Redis کش می‌شود.

ورودی‌ها

نام پارامتر نوع منبع الزامی توضیح
json string (JSON) Body بله آرایه‌ای از تراکنش‌ها شامل اطلاعات پرداخت و دریافتی.
branch integer JWT/Header بله کد شعبه مبدا برای محدودسازی تراکنش‌ها.
data[].type string Body→JSON بله نوع تراکنش (payment یا receive).
data[].type_pay string Body→JSON بله نوع پرداخت (transfer, accounting, coupon, contract).
data[].currency_amount integer Body→JSON بله مبلغ تراکنش (ریال).
data[].tracking_code string Body→JSON خیر کد رهگیری پرداخت در سیستم.
data[].wage integer Body→JSON خیر کارمزد تراکنش.
data[].functor_account integer Body→JSON خیر شناسه کاربر اجراکننده تراکنش (functor).
data[].status.id integer Body→JSON بله شناسه وضعیت تراکنش (در انتظار/تایید‌شده).

خروجی (Response)

{
  "status": true,
  "meta": {
    "timestamp": 1732287600
  },
  "inserted_count": 3,
  "ids": [1089, 1090, 1091],
  "cached_financial": true
}

نکات امنیتی

  • احراز JWT حتماً انجام می‌شود و شناسه شعبه از توکن استخراج می‌گردد.
  • ورودی JSON باید از لحاظ ساختار و مقادیر کلیدی اعتبارسنجی شود.
  • رشته‌های عددی مانند مبلغ حتماً قبل از درج به فرمت انگلیسی تبدیل می‌شوند تا از تزریق داده جلوگیری شود.

نکات عملکردی

  • درج گروهی رکوردها با استفاده از DB::table('pays')->insert() انجام می‌شود که سرعت بالایی دارد.
  • در انتهای عملیات، بلافاصله کش Redis برای حساب‌های reference و aggregation به‌روزرسانی می‌شود.
  • پیشنهاد به batch insert به همراه pipeline Redis (TTLs=300s) برای بازدهی بهتر.

وابستگی‌ها

  • use Illuminate\Support\Facades\DB;
  • use Illuminate\Support\Facades\Redis;
  • use Carbon\Carbon;
  • use App\Http\Controllers\TradeController;
  • use App\Http\Controllers\StaticController;

کدهای خطا

کد شرح خطا منبع
400 ورودی JSON نامعتبر یا پارامتر ناقص. json_decode()
403 کاربر بدون مجوز برای انجام نوع تراکنش. authWithJwt
500 خطا در ثبت گروهی یا بروزرسانی کش Redis. DB/Redis

پیشنهادهای امنیتی

  • کنترل دسترسی بر اساس نقش: فقط کاربران با سطح financial.editor مجاز به درج هستند.
  • رمزنگاری tracking_code در صورت ارسال از کلاینت‌های عمومی.
  • جلوگیری از ارسال دوباره (duplicate) در درخواست‌های همزمان با قفل Redis.

پیشنهادهای بهبود

  • افزودن امکان rollback خودکار در صورت خطا در بروزرسانی کش.
  • مدیریت تراکنش چندمرحله‌ای با Savepoints برای atomicity بهتر.
  • پشتیبانی از چند واحد پولی هم‌زمان (multi-currency).

ممیزی و لاگ‌ها

  • نوع لاگ: StorePayTransaction.
  • فیلدهای ثبت: operator_id، branch، ids، currency_amount.
  • سطح لاگ: Critical.
  • مدت نگهداری: ۹۰ روز در پایگاه audit_logs.

جمع‌بندی

این مسیر مسئول ثبت تراکنش‌های پرداخت و دریافتی و بروزرسانی مالی Redis است. عملیات سریع گروهی و مدیریت مالی اتومات باعث کاهش سربار حسابداری می‌شود. فعال‌سازی کنترل نقش و اعتبارسنجی ساختار JSON برای امنیت ضروری است.

Back to top