# POST /api/v2/panel/bulk/add

<div id="bkmrk-panel-bulk-add" 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;">POST</td><td style="direction: ltr; text-align: left;">/api/v2/panel/bulk/add</td><td style="direction: ltr; text-align: left;">V2BaseController@smsPanelAddBulk</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-smspaneladdbulk" style="direction: rtl; text-align: justify;">تابع **smsPanelAddBulk** از طریق اتصال به API سرویس `Melipayamak` فرآیند ارسال انبوه پیامک را انجام می‌دهد: - اطلاعات اتصال سرویس از جدول `application_interface` برای نوع `sms` و شعبه فعلی استخراج می‌شود.
- با ساخت شیء `new MelipayamakApi($username, $password)` به توابع `send()` یا `bulkSend()` متصل می‌شود.
- پارامترهای ورودی مانند شماره ارسال، متن پیام و شناسه گروه‌ها در بدنه درخواست تجمیع می‌شود.
- در صورت موفقیت، شناسهٔ کمپین (bulk\_id) از سمت سرویس دریافت و در جدول لاگ داخلی (در صورت وجود) ذخیره می‌گردد.
- در صورت خطا، کد و پیام خطای SOAP در خروجی 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><tr><td>text</td><td>string</td><td>بله</td><td>متن پیام قابل ارسال به مخاطبین</td></tr><tr><td>sender</td><td>string</td><td>خیر</td><td>شماره فرستنده (پیش‌فرض از تنظیمات سرویس استخراج می‌شود)</td></tr><tr><td>contacts</td><td>array\[int\]</td><td>بله</td><td>آرایه‌ای از شماره‌ها یا شناسه‌های گروه مخاطبین برای ارسال</td></tr><tr><td>scheduleTime</td><td>string</td><td>خیر</td><td>زمان‌بندی ارسال در صورت نیاز (فرمت ISO یا Jalali)</td></tr></tbody></table>

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

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

{
  "branch": 5,
  "text": "🎉 پروازهای ویژه نوروز با تخفیف تا ۳۰٪!",
  "contacts": [ "09351234567", "09125554433" ],
  "scheduleTime": "2025-03-01T10:00:00Z"
}
```

### خروجی (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>status</td><td>boolean</td><td>موفقیت یا شکست عملیات ارسال</td></tr><tr><td>bulk\_id</td><td>integer</td><td>شناسه کمپین ارسال (توسط سرویس پیامکی تولید می‌شود)</td></tr><tr><td>meta.timestamp</td><td>integer</td><td>زمان یونیکس درخواست یا پاسخ</td></tr><tr><td>error</td><td>object|null</td><td>در صورت شکست، شامل پیام و کد خطا است</td></tr></tbody></table>

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

```
{
  "status": true,
  "bulk_id": 1115,
  "meta": {
    "timestamp": 1732290514
  }
}
```

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

```
{
  "status": false,
  "error": {
    "code": 500,
    "message": "Error connecting to Melipayamak API"
  },
  "meta": {
    "timestamp": 1732290514
  }
}
```

### نکات امنیتی

- ارسال فقط برای شعبه معتبر بر اساس JWT امکان‌پذیر است.
- خطر ارسال پیام‌های غیرمجاز توسط اپراتورهای شعبه بدون نقش محدودکننده وجود دارد.
- باید مکانیزم `RoleRestriction(sms_sender)` فعال شود تا فقط کاربران مجاز بتوانند از این endpoint استفاده کنند.

### نکات عملکردی

- ارسال دسته‌ای بیش از 1000 شماره باعث تاخیر 5–7 ثانیه‌ای در پاسخ می‌شود.
- پیشنهاد: صف‌بندی درخواست‌ها با `Queue::dispatch(SMSBulkJob)` برای کاهش latency.
- در حال حاضر caching Redis وجود ندارد، ولی برای گزارش‌های تکراری بهتر است اضافه شود.

### وابستگی‌ها

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

### کدهای خطا

<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>2001</td><td>درخواست فاقد شماره ارسال معتبر</td><td>smsPanelAddBulk()</td></tr><tr><td>500</td><td>خطای ارتباط یا پاسخ نامعتبر از سرویس Melipayamak</td><td>MelipayamakApi::bulkSend()</td></tr></tbody></table>

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

- لاگ‌کردن هر کمپین ارسالی با `SystemLog::dispatch(["type" => "BulkSMSSent", ...])`.
- رمزنگاری متون پیام قبل از ذخیره در دیتابیس داخلی.
- افزودن کنترل ضد هرزنامه (anti-spam) برای جلوگیری از ارسال انبوه در بازه کوتاه.

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

- افزودن پارامتر `bulk_label` برای نام‌گذاری کمپین‌ها در گزارشات مدیریتی.
- افزودن حالت test-mode برای ارسال به تعداد محدود مخاطب جهت تست.
- افزودن پاسخ تکمیلی با تعداد پیام موفق و ناموفق.

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

- پیشنهاد ثبت هر ارسال در جدول `sms_audit` با فیلدهای `branch, bulk_id, sender, count, status`.
- در نسخه فعلی لاگ internal فعال نیست.

### جمع‌بندی

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