#P1389
POST /api/auth/connect/otp
Route Info
| Method | Endpoint | Controller | Middleware | Purpose | تگ Swagger |
| POST | /api/auth/connect/otp | UserController@connectOtp | domainAccess, ipTrust | ارسال رمز موقت جهت اتصال اپراتور به سرویسهای خارجی (نظیر تلگرام) | tags={"Auth"} |
توضیح عملکرد (Function Logic)
این Endpoint برای اپراتورهایی طراحی شده که قصد اتصال حساب کاربریشان به سرویسهای جانبی مانند ربات تلگرام را دارند. سیستم پس از بررسی اصالت اپراتور و اطمینان از عدم اتصال قبلی، رمز ۸ رقمی موقتی (OTP) صادر کرده و از طریق پیامک برای او ارسال میکند. هر کاربر مجاز است حداکثر ۳ بار در بازه ۵ ساعته درخواست ارسال OTP ثبت کند.
- بررسی وضعیت و مشخصات اپراتور بر اساس
personnel_idو وضعیت فعال. - بررسی عدم اتصال قبلی به تلگرام (
telegram IS NULL). - کنترل سقف ارسال OTP در ۵ ساعت گذشته با
Visa::showSystemLogs. - صدور OTP عددی ۸ رقمی و ذخیره در
operators.otpهمراه زمان صدور. - ارسال پیامک OTP از طریق
StaticController::sendNotification. - ثبت رویداد
SystemLogبا تاخیر ۱۰ دقیقهای در صفsnailJob.
ورودیها (Inputs)
| پارامتر | نوع داده | الزامی | توضیح |
| personnel_id | string | بله | کد پرسنلی اپراتور فعال (status=1) برای تأیید هویت |
| branch | integer | خیر | شناسه شعبه برای انتخاب مسیر ارسال پیامک (در سرویس ارسال Notification) |
نمونه درخواست:
POST /api/auth/connect/otp
Content-Type: application/json
{
"personnel_id": "P00157",
"branch": 2
}
خروجیها (Outputs)
ارسال موفق OTP
{
"status": true,
"time": 1731963200,
"message": "OTP با موفقیت ارسال گردید."
}
اطلاعات کاربر یافت نشد
{
"status": false,
"code": 1201,
"message": "اطلاعات وارد شده با هیچ کاربری همخوانی ندارد"
}
کاربر قبلاً متصل شده است
{
"status": false,
"code": 1203,
"message": "شما قبلا به سامانه متصل شده اید اگر قصد تغییر تلگرام خود را دارید قبل از انجام این فرایند. از طریق سامانه قطع اتصال فرمائید."
}
تعداد درخواست بیش از حد مجاز
{
"status": false,
"code": 1203,
"message": "تعداد درخواست های کاربر بیش از حد مجاز بوده است. لطفا 5 ساعت دیگر اقدام نمائید."
}
پیامک ارسال نشد
{
"status": false,
"code": 1202,
"message": "پیامک OTP ارسال نشد. مشکلی رخ داده است. لطفا دوباره تلاش کنید",
"trace": {...}
}
محدودسازی ارسال (Throttle Control)
ارسال OTP به کمک بررسی لاگهای
SystemLog انجام میگیرد. هر اپراتور مجاز به ارسال حداکثر ۳ بار در بازهی زمانی ۵ ساعت است. در صورت تجاوز از این حد پاسخ با کد 1203 بازمیگردد.قالب پیامک ارسالی (SMS Template)
code: 12345678 این رمز جهت ارتباط با سایر سرویس ها صادر شده است. از دراختیار قراردادن آن به دیگران جدا خودداری فرمائید. مدت اعتبار: 15 دقیقه 🌐 example.domain
ثبت رویداد SystemLog
پس از ارسال موفق پیامک، رویداد زیر در صف snailJob ثبت میگردد:
SystemLog::dispatch([
"type" => "SendOtp",
"goal" => operator_id,
"by" => operator_id,
"agent" => $_SERVER['HTTP_USER_AGENT'],
"ip" => getIP(),
"datetime" => now()
])->delay(now()->addMinutes(10))->onQueue('snailJob');
تغییرات دیتابیس (Database Update)
UPDATE operators
SET
otp = {random 8-digit code},
otp_issuing = NOW()
WHERE id = {operator.id};
وابستگیها (Dependencies)
- use Illuminate\Http\Request;
- use Illuminate\Support\Facades\DB;
- use Carbon\Carbon;
- use App\Jobs\SystemLog;
- use App\Http\Controllers\StaticController;
- use App\Services\Visa;
نمونه تست (Postman Example)
POST https://console.service01.ir/api/auth/connect/otp
Content-Type: application/json
{
"personnel_id": "P00231",
"branch": 1
}
تحلیل امنیتی
- اگر کاربر قبلاً به تلگرام متصل شده باشد، ارسال OTP انجام نمیشود.
- رمز ۸ رقمی تنها ۱۵ دقیقه معتبر است.
- کنترل دفعات درخواست در بازهی ۵ ساعت مانع حملات brute force میشود.
- دسترسی به این مسیر فقط از IPها و دامنههای مجاز امکانپذیر است (بهواسطهی
domainAccessوipTrust).
پیوست نگهداری و توسعهآتی
- افزودن سیستم Push Notification برای ارتباط درونبرنامهای بهجای پیامک.
- ثبت IP درخواست OTP در جدول جداگانه برای تحلیل امنیتی.
- ادغام با سامانه مرکزی Auth برای مدیریت اتصال سایر سرویسها.
- افزودن شاخص
otp_fail_attemptsبرای کنترل تلاشهای اشتباه.