# GET /api/v2/panel/bulk/receptions

<div id="bkmrk-panel-bulk-receptions" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### Route Info

<table border="1" cellpadding="6" id="bkmrk-method-endpoint-cont" style="margin: 15px auto; width: 95%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>Method</td><td>Endpoint</td><td>Controller</td><td>Middleware</td><td>Purpose</td></tr><tr><td style="direction: ltr; text-align: left;">GET</td><td style="direction: ltr; text-align: left;">/api/v2/panel/bulk/receptions</td><td style="direction: ltr; text-align: left;">V2BaseController@smsPanelGetBulkReceptions</td><td style="direction: ltr; text-align: left;">authWithJwt</td><td style="direction: rtl; text-align: right;">دریافت لیست پیام‌های انبوه ارسال‌شده در پنل پیامک فعال برای شعبه فعلی</td></tr></tbody></table>

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

<div id="bkmrk-%D8%AA%D8%A7%D8%A8%D8%B9-smspanelgetbulk" style="direction: rtl; text-align: justify;">تابع **smsPanelGetBulkReceptions** به سرویس پیامکی متصل شده و داده‌های آماری پیام‌های گروهی ارسال‌شده را بازیابی می‌کند: - با استفاده از تنظیمات موجود در جدول `application_interface` سرویس `sms` فعال شعبه یافت می‌شود.
- متد `getBulkReceptions()` از کلاس SDK `MelipayamakApi` فراخوانی شده و فهرست پیام‌های گروهی بازگردانده می‌شود.
- هر پیام به آرایه‌ای شامل شناسه، فرستنده، متن، تعداد گیرندگان، زمان ارسال و درصد موفقیت تبدیل می‌گردد.
- در نهایت، داده‌ها به صورت JSON با وضعیت موفقیت و زمان یونیکس بازگردانده می‌شوند.

</div>### ورودی‌ها (Request Fields)

<table border="1" cellpadding="6" id="bkmrk-%D9%86%D8%A7%D9%85-%D9%81%DB%8C%D9%84%D8%AF-%D9%86%D9%88%D8%B9-%D8%AF%D8%A7%D8%AF%D9%87-%D8%A7%D9%84" style="margin: 15px auto; width: 97%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>نام فیلد</td><td>نوع داده</td><td>الزامی</td><td>توضیح</td></tr><tr><td>branch</td><td>integer</td><td>بله</td><td>شناسه شعبه جهت بازیابی تنظیمات سرویس پیامکی</td></tr></tbody></table>

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

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

?branch=5
```

### خروجی (Response)

<table border="1" cellpadding="6" id="bkmrk-%D9%81%DB%8C%D9%84%D8%AF-%D9%86%D9%88%D8%B9-%D8%AF%D8%A7%D8%AF%D9%87-%D8%AA%D9%88%D8%B6%DB%8C%D8%AD-" style="margin: 15px auto; width: 97%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>فیلد</td><td>نوع داده</td><td>توضیح</td></tr><tr><td>bulk\_id</td><td>integer</td><td>شناسه یکتا کمپین ارسال پیامک گروهی</td></tr><tr><td>sender</td><td>string</td><td>شماره فرستنده پیام</td></tr><tr><td>text</td><td>string</td><td>متن پیام ارسال‌شده</td></tr><tr><td>count</td><td>integer</td><td>تعداد کل گیرندگان پیام</td></tr><tr><td>delivered</td><td>integer</td><td>تعداد پیام‌های موفق تحویل‌شده</td></tr><tr><td>failed</td><td>integer</td><td>تعداد پیام‌های ناموفق یا رد‌شده</td></tr><tr><td>datetime</td><td>string</td><td>زمان ارسال کمپین (فرمت ISO)</td></tr><tr><td>success\_rate</td><td>float</td><td>نسبت موفقیت تحویل پیام‌ها (درصد)</td></tr></tbody></table>

#### نمونه پاسخ:

```
{
  "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;

### کدهای خطا

<table border="1" cellpadding="6" id="bkmrk-%DA%A9%D8%AF-%D8%B4%D8%B1%D8%AD-%D8%AE%D8%B7%D8%A7-%D9%85%D9%86%D8%A8%D8%B9-1006" style="margin: 15px auto; width: 90%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>کد</td><td>شرح خطا</td><td>منبع</td></tr><tr><td>1006</td><td>توکن JWT نامعتبر یا منقضی شده</td><td>authWithJwt</td></tr><tr><td>404</td><td>عدم یافتن تنظیمات سرویس پیامک برای شعبه</td><td>smsPanelGetBulkReceptions()</td></tr><tr><td>500</td><td>خطای پاسخ از سرویس Melipayamak یا SOAP Data Invalid</td><td>MelipayamakApi::getBulkReceptions()</td></tr></tbody></table>

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

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

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

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

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

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

### جمع‌بندی

<div id="bkmrk-%D9%85%D8%B3%DB%8C%D8%B1-%2Fpanel%2Fbulk%2Frec" style="direction: rtl; text-align: justify;">مسیر **/panel/bulk/receptions** به عنوان بخش گزارش پیام‌های انبوه پنل پیامکی عمل می‌کند. داده‌های خروجی ساده و بدون نقش‌بندی است و در نسخه فعلی به عنوان نقطه ضعف امنیتی شناخته می‌شود. در ساختار Enterprise لازم است احراز نقش و ساختار audit کامل افزوده گردد و caching دوره‌ای برای سنجش عملکرد سرویس پیامک فعال شود.</div>