#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 برای کنترل تلاش‌های اشتباه.