Skip to main content
#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 دوره‌ای برای سنجش عملکرد سرویس پیامک فعال شود.
Back to top