#P1474

GET /api/v2/panel/bulk/receptions

Route Info

Method	Endpoint	Controller	Middleware	Purpose
GET	/api/v2/panel/bulk/receptions	V2BaseController@smsPanelGetBulkReceptions	authWithJwt	دریافت لیست پیام‌های انبوه ارسال‌شده در پنل پیامک فعال برای شعبه فعلی

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

تابع smsPanelGetBulkReceptions به سرویس پیامکی متصل شده و داده‌های آماری پیام‌های گروهی ارسال‌شده را بازیابی می‌کند:

با استفاده از تنظیمات موجود در جدول application_interface سرویس sms فعال شعبه یافت می‌شود.
متد getBulkReceptions() از کلاس SDK MelipayamakApi فراخوانی شده و فهرست پیام‌های گروهی بازگردانده می‌شود.
هر پیام به آرایه‌ای شامل شناسه، فرستنده، متن، تعداد گیرندگان، زمان ارسال و درصد موفقیت تبدیل می‌گردد.
در نهایت، داده‌ها به صورت JSON با وضعیت موفقیت و زمان یونیکس بازگردانده می‌شوند.

ورودی‌ها (Request Fields)

نام فیلد	نوع داده	الزامی	توضیح
branch	integer	بله	شناسه شعبه جهت بازیابی تنظیمات سرویس پیامکی

نمونه درخواست:

GET /api/v2/panel/bulk/receptions
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

?branch=5

خروجی (Response)

فیلد	نوع داده	توضیح
bulk_id	integer	شناسه یکتا کمپین ارسال پیامک گروهی
sender	string	شماره فرستنده پیام
text	string	متن پیام ارسال‌شده
count	integer	تعداد کل گیرندگان پیام
delivered	integer	تعداد پیام‌های موفق تحویل‌شده
failed	integer	تعداد پیام‌های ناموفق یا رد‌شده
datetime	string	زمان ارسال کمپین (فرمت ISO)
success_rate	float	نسبت موفقیت تحویل پیام‌ها (درصد)

نمونه پاسخ:

{
  "status": true,
  "meta": { "timestamp": 1732290419 },
  "items": [
    {
      "bulk_id": 9021,
      "sender": "5000400008851",
      "text": "تخفیف ویژه پروازهای داخلی فقط امروز!",
      "count": 1320,
      "delivered": 1287,
      "failed": 33,
      "datetime": "2025-11-22T08:15:00Z",
      "success_rate": 97.5
    },
    {
      "bulk_id": 8904,
      "sender": "5000400008851",
      "text": "اعلان تغییر قوانین رزرو آنلاین",
      "count": 698,
      "delivered": 684,
      "failed": 14,
      "datetime": "2025-11-20T06:43:00Z",
      "success_rate": 97.9
    }
  ]
}

نکات امنیتی

وابسته به اعتبار توکن JWT و سطح دسترسی پیامکی شعبه.
اطلاعات پیام‌های انبوه ممکن است شامل متن‌های حساس یا تبلیغاتی باشد — پیشنهاد رمزنگاری ذخیرهٔ محلی.
فیلتر نقش در نسخه فعلی وجود ندارد؛ هر اپراتور شعبه می‌تواند کل فهرست را مشاهده کند.

عملکرد و کارایی

تابع سریع اما وابسته به latency سرویس خارجی.
در فراخوانی‌های متوالی توصیه می‌شود cache محدود Redis برای مدت ۵ دقیقه ایجاد گردد.
مدت پاسخ معمولی بین ۲ تا ۳ ثانیه (بسته به حجم داده).

وابستگی‌ها

use App\Lib\MelipayamakApi;
use Illuminate\Support\Facades\DB;
use Illuminate\Http\Request;
use Exception;

کدهای خطا

کد	شرح خطا	منبع
1006	توکن JWT نامعتبر یا منقضی شده	authWithJwt
404	عدم یافتن تنظیمات سرویس پیامک برای شعبه	smsPanelGetBulkReceptions()
500	خطای پاسخ از سرویس Melipayamak یا SOAP Data Invalid	MelipayamakApi::getBulkReceptions()

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

اعمال Role-based Access فقط برای کاربرانی با نقش sms_manager.
ثبت لاگ برای هر مشاهده داده پیامک گروهی (type: ViewBulkSMS).
پنهان‌سازی متن پیام در حالت عمومی؛ فقط در حالت administrative نمایش داده شود.

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

افزودن فیلدهای cost و provider_response_time برای تحلیل اقتصادی ارسال پیام‌ها.
افزودن endpoint فیلتر بر اساس بازه زمانی و درصد موفقیت.
ایجاد Caching مبتنی بر Redis با prefetch خودکار داده‌ها برای شعب فعال.

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

در نسخه فعلی هیچ ممیزی خروجی برای مشاهده پیام‌های انبوه انجام نمی‌شود.
پیشنهاد: ثبت در جدول system_logs با رویداد BulkSMSViewed.

جمع‌بندی

مسیر /panel/bulk/receptions به عنوان بخش گزارش پیام‌های انبوه پنل پیامکی عمل می‌کند. داده‌های خروجی ساده و بدون نقش‌بندی است و در نسخه فعلی به عنوان نقطه ضعف امنیتی شناخته می‌شود. در ساختار Enterprise لازم است احراز نقش و ساختار audit کامل افزوده گردد و caching دوره‌ای برای سنجش عملکرد سرویس پیامک فعال شود.

Revision #1
Created 2025-11-22 13:26:41 UTC by Alireza
Updated 2025-11-22 13:27:08 UTC by Alireza