#P1473
GET /api/v2/panel/groups/get
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| GET |
/api/v2/panel/groups/get |
V2BaseController@smsPanelGetGroups |
authWithJwt |
دریافت گروههای دفترچه مخاطبین سرویس پیامک فعال (SMS Panel) برای شعبه فعلی |
منطق عملکرد تابع
تابع
smsPanelGetGroups برای اتصال به سرویس پیامک Melipayamak (API رسمی شرکت پرداخت اول) طراحی شده است:
- ابتدا اطلاعات اتصال از جدول
application_interface واکشی میشود (فیلدهای service، username، password و data->sender).
- در صورت یافتن تنظیمات معتبر، شیء API با
MelipayamakApi ساخته میشود و به متد contacts() متصل میگردد.
- با فراخوانی متد
getGroups()، لیست گروههای موجود در دفترچه مخاطبین واکشی میشود.
- خروجی به آرایهٔ قابلخواندن شامل شناسه گروه، عنوان، توضیحات، وضعیت، تعداد مخاطبین و اطلاعات زیرگروه تبدیل میگردد.
- در صورت عدم یافتن تنظیمات معتبر یا وجود خطا، مسیر مقدار خالی یا خطای سطح ۴۰۰ بازمیگرداند.
| نام فیلد |
نوع داده |
الزامی |
توضیح |
| branch |
integer |
بله |
شناسه شعبه جهت تعیین سرویس فعال پیامک |
نمونه درخواست:
GET /api/v2/panel/groups/get
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json
?branch=5
خروجی (Response)
| فیلد |
نوع داده |
توضیح |
| id |
integer |
شناسه یکتا گروه مخاطبین |
| user_id |
integer |
شناسه کاربر در سرویس پیامک |
| parent |
integer|null |
شناسه زیرگروه یا گروه مادر |
| title |
string |
عنوان گروه |
| description |
string |
توضیحات گروه |
| count |
integer |
تعداد کل مخاطبین موجود در گروه |
| status |
integer |
وضعیت فعال بودن گروه (۱=فعال، ۰=غیرفعال) |
| child.show |
boolean |
نمایش زیرگروهها برای کودکها (true/false) |
| child.count |
integer |
تعداد زیرگروهها |
نمونه پاسخ:
[
{
"id": 122,
"user_id": 931,
"parent": null,
"title": "مشتریان ویژه",
"description": "VIP Contacts Reserved",
"count": 312,
"status": 1,
"child": {
"show": true,
"count": 4
}
},
{
"id": 127,
"user_id": 931,
"parent": 122,
"title": "آژانس همکاران",
"description": "",
"count": 151,
"status": 1,
"child": {
"show": false,
"count": 0
}
}
]
نکات امنیتی
- وابسته به JWT معتبر و فعال بودن سرویس پیامکی شعبه.
- در صورت نبود سرویس پیامک برای شعبه، پاسخ خالی یا کد خطای ۴۰۴ باید بازگردد.
- عدم رمزنگاری داده خروجی بهدلیل عمومی بودن داده مخاطبین (اما بهتر است برای دادههای شرکت خصوصی رمزگذاری شود).
- تابع سبک است اما وابسته به latency سرویس SOAP خارجی (Melipayamak).
- پاسخ معمولاً طی ۱ تا ۳ ثانیه بسته به حجم گروهها بازگردانده میشود.
- پیشنهاد: cache گروهها در Redis برای مدت ۱۰ دقیقه جهت جلوگیری از تکرار درخواست به سرویس خارجی.
وابستگیها
- use Illuminate\Support\Facades\DB;
- use App\Lib\MelipayamakApi;
- use Illuminate\Http\Request;
- use Exception;
کدهای خطا
| کد |
شرح خطا |
منبع |
| 1006 |
توکن JWT نامعتبر یا منقضی شده |
authWithJwt |
| 404 |
تنظیمات سرویس پیامک برای این شعبه یافت نشد |
smsPanelGetGroups() |
| 500 |
خطای اتصال با سرویس Melipayamak یا پاسخ نامعتبر SOAP |
MelipayamakApi::contacts() |
پیشنهادهای امنیتی
- ماسک کردن اطلاعات کاربر سرویس پیامک (مانند password) در سطح API داخلی.
- افزودن audit برای هر فراخوانی دفترچه مخاطبین از پنل.
- استفاده از اتصال HTTPS برای ارتباط مستقیم با Melipayamak API.
پیشنهادهای بهبود
- افزودن endpoint مکمل برای واکشی اعضای هر گروه (GET /panel/groups/{group_id}/members).
- نمایش تعداد پیامهای ارسالشده یا وضعیت فعال در خروجی.
- امکان فیلتر بر اساس عنوان، وضعیت و تاریخ ایجاد گروه.
ممیزی و لاگها
- در نسخه فعلی لاگ ثبت درخواست انجام نمیشود.
- پیشنهاد: ذخیرهی داده تماس در جدول
system_logs با نوع رخداد ViewSMSGroups.
جمعبندی
مسیر /panel/groups/get برای هماهنگی مستقیم با API پیامکی استفاده میشود. هرچند پاسخ سبک و خوانا دارد، اما به دلیل عدم کش داخلی (caching) در نسخه فعلی میتواند موجب افزایش latency سیستم شود. در نسخهی حرفهای باید caching و محدودیت فراخوانی Request Rate در هر شعبه اضافه گردد.