#P1534
POST /asterisk/ussd/send
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| POST |
/api/v2/asterisk/ussd/send |
AsteriskAmiController@sendUssd |
authWithJwt |
ارسال دستور USSD در ماژول Asterisk و دریافت پاسخ از شبکه مخابراتی |
منطق عملکرد تابع
تابع sendUssd دستورات کوتاه USSD را به کمک پروتکل AMI به دستگاه GSM ارسال میکند. ابتدا مقدار پارامتر code بررسی شده و فرمت آن با الگوی USSD تطبیق مییابد (مثلاً *1*123#). در صورت صحت، دستور با Action DongleSendUssd به AMI فرستاده میشود و در پایگاه داده به عنوان درخواست ثبت میشود. پاسخ خام AMI بر اساس رویداد DongleUSSD دریافت شده، در جدول ami_ussd_logs ذخیره و از طریق وبسوکت در کانال ussd_notification به کاربر منتشر میشود.
- اعتبارسنجی پارامترهای
code و device.
- بررسی اتصال به AMI و دسترس بودن دستگاه مورد نظر.
- ارسال دستور USSD از طریق Action
DongleSendUssd.
- ثبت در
ami_ussd_logs، تماس با وبسوکت برای اعلان.
- بازگرداندن نتیجه به صورت JSON با پاسخ وضعیت شبکه.
پارامترهای ورودی
| نام |
محل |
نوع |
الزامی |
توضیح |
| code |
Body |
string |
بله |
کد USSD مثلاً *140*1# |
| device |
Body |
string |
خیر |
شناسه دستگاه (مثل dongle1) |
ساختار خروجی
{
"status": true,
"message": "USSD command sent successfully",
"data": {
"id": "USSD-1732362009",
"code": "*140*1#",
"device": "dongle1",
"response": "Your remaining balance is 74,250 IRR",
"timestamp": "2025-11-23T15:10:09+03:30"
}
}
نکات امنیتی
- این مسیر فقط برای کاربران با نقش
telecom_operator یا system_admin قابل دسترسی است.
- در صورت ارسال کدهای USSD خطرناک (مانند ریست تنظیمات سیمکارت)، درخواست رد و در
system_logs ثبت میشود.
- کلیه درخواستها و پاسخهای شبکه در
ami_ussd_logs مانیتور میشوند.
عملکرد
- میانگین زمان تبادل با شبکه: ۱۰۰–۳۰۰ میلیثانیه.
- پاسخ USSD در اکثر شبکهها در کمتر از ۲ ثانیه دریافت میشود.
Dependencies
- use App\Services\Ami;
- use App\Services\NotificationService;
- use Illuminate\Support\Facades\Redis;
- use Carbon\Carbon;
کدهای خطا
| کد |
شرح |
منبع |
| 400 |
ورودی نامعتبر یا کد USSD غیراستاندارد |
Validation |
| 401 |
توکن JWT نامعتبر |
Authentication |
| 403 |
عدم مجوز ارسال USSD |
Authorization |
| 500 |
عدم پاسخ از AMI |
AMI Gateway |
| 504 |
Timeout در پاسخ شبکه USSD |
Network |
پیشنهادهای امنیتی
- ثبت سطح دسترسی بر اساس شماره سیم کارت (IMEI).
- اعمال Rate Limit ۱ درخواست در هر ۳ ثانیه به ازای هر دستگاه.
پیشنهادهای توسعهای
- افزودن پارامتر
auto_reply برای تعامل چندمرحلهای با USSD.
- ثبت تاریخی از پرسوجوهای سیمکارت برای مصارف آمارگیری.
ممیزی و لاگها
- ثبت در
ami_ussd_logs با فیلدهای code، device، response، operator_id.
- ثبت رویداد در
system_logs با کلید asterisk_send_ussd.
جمعبندی
sendUssd امکان مدیریت دستورات USSD را از طریق Asterisk فراهم میآورد و برای عملیاتهایی مانند بررسی اعتبار، خرید بسته یا مدیریت سیمکارت استفاده میشود. این ماژول در سطح enterprise طراحی شده و دارای لاگ، وبسوکت و امنیت چندسطحی است.
