# POST /api/auth/connect/otp

<div id="bkmrk-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;"></div>### Route Info

<div id="bkmrk-method-endpoint-cont" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;"><table border="1" cellpadding="6" cellspacing="0" style="margin: 15px auto; width: 95%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>Method</td><td>Endpoint</td><td>Controller</td><td>Middleware</td><td>Purpose</td><td>تگ Swagger</td></tr><tr><td style="direction: ltr; text-align: left;">POST</td><td style="direction: ltr; text-align: left;">/api/auth/connect/otp</td><td style="direction: ltr; text-align: left;">UserController@connectOtp</td><td style="direction: ltr; text-align: left;">domainAccess, ipTrust</td><td style="direction: rtl; text-align: right;">ارسال رمز موقت جهت اتصال اپراتور به سرویس‌های خارجی (نظیر تلگرام)</td><td style="direction: ltr; text-align: left;">tags={"Auth"}</td></tr></tbody></table>

</div>### توضیح عملکرد (Function Logic)

<div id="bkmrk-%D8%A7%DB%8C%D9%86-endpoint-%D8%A8%D8%B1%D8%A7%DB%8C-%D8%A7%D9%BE" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;"><div style="direction: rtl; text-align: justify;">این Endpoint برای اپراتورهایی طراحی شده که قصد اتصال حساب کاربریشان به سرویس‌های جانبی مانند ربات تلگرام را دارند. سیستم پس از بررسی اصالت اپراتور و اطمینان از عدم اتصال قبلی، رمز ۸ رقمی موقتی (OTP) صادر کرده و از طریق پیامک برای او ارسال می‌کند. هر کاربر مجاز است حداکثر ۳ بار در بازه ۵ ساعته درخواست ارسال OTP ثبت کند.</div>1. بررسی وضعیت و مشخصات اپراتور بر اساس `personnel_id` و وضعیت فعال.
2. بررسی عدم اتصال قبلی به تلگرام (`telegram IS NULL`).
3. کنترل سقف ارسال OTP در ۵ ساعت گذشته با `Visa::showSystemLogs`.
4. صدور OTP عددی ۸ رقمی و ذخیره در `operators.otp` همراه زمان صدور.
5. ارسال پیامک OTP از طریق `StaticController::sendNotification`.
6. ثبت رویداد `SystemLog` با تاخیر ۱۰ دقیقه‌ای در صف `snailJob`.

</div>### ورودی‌ها (Inputs)

<div id="bkmrk-%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1-%D9%86%D9%88%D8%B9-%D8%AF%D8%A7%D8%AF%D9%87-%D8%A7%D9%84%D8%B2" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;"><table border="1" cellpadding="6" cellspacing="0" style="margin: 15px auto; width: 95%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>پارامتر</td><td>نوع داده</td><td>الزامی</td><td>توضیح</td></tr><tr><td>personnel\_id</td><td>string</td><td>بله</td><td style="direction: rtl; text-align: right;">کد پرسنلی اپراتور فعال (status=1) برای تأیید هویت</td></tr><tr><td>branch</td><td>integer</td><td>خیر</td><td style="direction: rtl; text-align: right;">شناسه شعبه برای انتخاب مسیر ارسال پیامک (در سرویس ارسال Notification)</td></tr></tbody></table>

<div style="direction: rtl; text-align: justify;">نمونه درخواست:</div></div>```
POST /api/auth/connect/otp
Content-Type: application/json

{
  "personnel_id": "P00157",
  "branch": 2
}
```

<div id="bkmrk--1" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;"></div>### خروجی‌ها (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": {...}
}
```

<div id="bkmrk--2" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;"></div>### محدودسازی ارسال (Throttle Control)

<div id="bkmrk-%D8%A7%D8%B1%D8%B3%D8%A7%D9%84-otp-%D8%A8%D9%87-%DA%A9%D9%85%DA%A9-%D8%A8%D8%B1%D8%B1" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;"><div style="direction: rtl; text-align: justify;">ارسال OTP به کمک بررسی لاگ‌های `SystemLog` انجام می‌گیرد. هر اپراتور مجاز به ارسال حداکثر **۳ بار** در بازه‌ی زمانی **۵ ساعت** است. در صورت تجاوز از این حد پاسخ با کد 1203 بازمی‌گردد.</div></div>### قالب پیامک ارسالی (SMS Template)

```
code: 12345678
این رمز جهت ارتباط با سایر سرویس ها صادر شده است.
از دراختیار قراردادن آن به دیگران جدا خودداری فرمائید.
مدت اعتبار: 15 دقیقه

🌐 example.domain
```

<div id="bkmrk--3" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;"></div>### ثبت رویداد SystemLog

<div id="bkmrk-%D9%BE%D8%B3-%D8%A7%D8%B2-%D8%A7%D8%B1%D8%B3%D8%A7%D9%84-%D9%85%D9%88%D9%81%D9%82-%D9%BE%DB%8C%D8%A7" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;"><div style="direction: rtl; text-align: justify;">پس از ارسال موفق پیامک، رویداد زیر در صف **snailJob** ثبت می‌گردد:</div></div>```
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');
```

<div id="bkmrk--4" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;"></div>### تغییرات دیتابیس (Database Update)

```
UPDATE operators
SET
  otp = {random 8-digit code},
  otp_issuing = NOW()
WHERE id = {operator.id};
```

<div id="bkmrk--5" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;"></div>### وابستگی‌ها (Dependencies)

<div id="bkmrk-use-illuminate%5Chttp%5C" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;">- 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;

</div>### نمونه تست (Postman Example)

```
POST https://console.service01.ir/api/auth/connect/otp
Content-Type: application/json

{
  "personnel_id": "P00231",
  "branch": 1
}
```

<div id="bkmrk--6" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;"></div>### تحلیل امنیتی

<div id="bkmrk-%D8%A7%DA%AF%D8%B1-%DA%A9%D8%A7%D8%B1%D8%A8%D8%B1-%D9%82%D8%A8%D9%84%D8%A7%D9%8B-%D8%A8%D9%87-%D8%AA" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;">- اگر کاربر قبلاً به تلگرام متصل شده باشد، ارسال OTP انجام نمی‌شود.
- رمز ۸ رقمی تنها ۱۵ دقیقه معتبر است.
- کنترل دفعات درخواست در بازه‌ی ۵ ساعت مانع حملات brute force می‌شود.
- دسترسی به این مسیر فقط از IPها و دامنه‌های مجاز امکان‌پذیر است (به‌واسطه‌ی `domainAccess` و `ipTrust`).

</div>### پیوست نگهداری و توسعه‌آتی

<div id="bkmrk-%D8%A7%D9%81%D8%B2%D9%88%D8%AF%D9%86-%D8%B3%DB%8C%D8%B3%D8%AA%D9%85-push-no" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;">- افزودن سیستم Push Notification برای ارتباط درون‌برنامه‌ای به‌جای پیامک.
- ثبت IP درخواست OTP در جدول جداگانه برای تحلیل امنیتی.
- ادغام با سامانه مرکزی Auth برای مدیریت اتصال سایر سرویس‌ها.
- افزودن شاخص `otp_fail_attempts` برای کنترل تلاش‌های اشتباه.

</div>