#P1475
POST /api/v2/panel/bulk/add
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| POST |
/api/v2/panel/bulk/add |
V2BaseController@smsPanelAddBulk |
authWithJwt |
ارسال پیامکهای انبوه به گروه یا فهرست مخاطبین تعیینشده از سمت پنل پیامکی شعبه |
منطق عملکرد تابع
تابع
smsPanelAddBulk از طریق اتصال به API سرویس
Melipayamak فرآیند ارسال انبوه پیامک را انجام میدهد:
- اطلاعات اتصال سرویس از جدول
application_interface برای نوع sms و شعبه فعلی استخراج میشود.
- با ساخت شیء
new MelipayamakApi($username, $password) به توابع send() یا bulkSend() متصل میشود.
- پارامترهای ورودی مانند شماره ارسال، متن پیام و شناسه گروهها در بدنه درخواست تجمیع میشود.
- در صورت موفقیت، شناسهٔ کمپین (bulk_id) از سمت سرویس دریافت و در جدول لاگ داخلی (در صورت وجود) ذخیره میگردد.
- در صورت خطا، کد و پیام خطای SOAP در خروجی JSON بازگردانده میشود.
| نام فیلد |
نوع داده |
الزامی |
توضیح |
| branch |
integer |
بله |
شناسه شعبه جهت شناسایی سرویس فعال پیامک |
| text |
string |
بله |
متن پیام قابل ارسال به مخاطبین |
| sender |
string |
خیر |
شماره فرستنده (پیشفرض از تنظیمات سرویس استخراج میشود) |
| contacts |
array[int] |
بله |
آرایهای از شمارهها یا شناسههای گروه مخاطبین برای ارسال |
| scheduleTime |
string |
خیر |
زمانبندی ارسال در صورت نیاز (فرمت ISO یا Jalali) |
نمونه درخواست:
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)
| فیلد |
نوع داده |
توضیح |
| status |
boolean |
موفقیت یا شکست عملیات ارسال |
| bulk_id |
integer |
شناسه کمپین ارسال (توسط سرویس پیامکی تولید میشود) |
| meta.timestamp |
integer |
زمان یونیکس درخواست یا پاسخ |
| error |
object|null |
در صورت شکست، شامل پیام و کد خطا است |
نمونه پاسخ موفق:
{
"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;
کدهای خطا
| کد |
شرح خطا |
منبع |
| 1006 |
توکن JWT نامعتبر یا منقضی شده |
authWithJwt |
| 2001 |
درخواست فاقد شماره ارسال معتبر |
smsPanelAddBulk() |
| 500 |
خطای ارتباط یا پاسخ نامعتبر از سرویس Melipayamak |
MelipayamakApi::bulkSend() |
پیشنهادهای امنیتی
- لاگکردن هر کمپین ارسالی با
SystemLog::dispatch(["type" => "BulkSMSSent", ...]).
- رمزنگاری متون پیام قبل از ذخیره در دیتابیس داخلی.
- افزودن کنترل ضد هرزنامه (anti-spam) برای جلوگیری از ارسال انبوه در بازه کوتاه.
پیشنهادهای بهبود
- افزودن پارامتر
bulk_label برای نامگذاری کمپینها در گزارشات مدیریتی.
- افزودن حالت test-mode برای ارسال به تعداد محدود مخاطب جهت تست.
- افزودن پاسخ تکمیلی با تعداد پیام موفق و ناموفق.
ممیزی و لاگها
- پیشنهاد ثبت هر ارسال در جدول
sms_audit با فیلدهای branch, bulk_id, sender, count, status.
- در نسخه فعلی لاگ internal فعال نیست.
جمعبندی
مسیر /panel/bulk/add نقطه ورود برای ارسال کمپینهای پیامکی است که با وجود عملکرد ساده، به دلیل عدم وجود نقشبندی و ممیزی میتواند به سوءاستفاده عملیاتی منجر شود. نسخهای که در Enterprise اجرا شود باید حتماً شامل تأیید سطح دسترسی، audit log لحظهای و ثبت پیامهای ارسالی بهصورت رمزگذاریشده باشد.
