POST/api/public/access-request/email/start-verification

یک کد تأیید ۶ رقمی معتبر به مدت ۱۰ دقیقه به آدرس ایمیل مشخصشده ارسال میکند — اولین گام قبل از درخواست دسترسی.

`POST /api/public/access-request/email/start-verification` تأیید ایمیل را برای یک درخواست دسترسی عمومی آغاز می‌کند. این درخواست نیازی به ورود به سیستم ندارد و آدرس مورد بررسی را در فیلد بدنه `email` شامل می‌شود. پس از پردازش موفق، سیستم یک کد تأیید شش‌رقمی ارسال می‌کند که ده دقیقه معتبر است. پاسخ شامل `ok`، یک `verification_id`، `expires_in_minutes` و `resend_cooldown_seconds` است. `verification_id` باید همراه با همان آدرس ایمیل و کد دریافتی در Verify-Route بعدی استفاده شود. این یک Login-Token نیست و نباید به عنوان شناسه کاربری دائمی ذخیره شود یا به صورت عمومی ثبت شود. نقطه پایانی غیر ایدمپوتنت است. چندین فراخوانی موفق می‌توانند چندین فرآیند تأیید یا کدهای جدید ایجاد کنند. بنابراین یک محدودیت سختگیرانه مبتنی بر IP برای ده درخواست در عرض ۱۵ دقیقه اعمال می‌شود. علاوه بر این، پاسخ به یک قفل تکرار ۶۰ ثانیه‌ای اشاره می‌کند. در این مدت، رابط کاربری نباید ارسال مجددی را آغاز کند و باید زمان انتظار باقی‌مانده را به‌طور قابل فهم نمایش دهد. اگر حد مجاز فراتر رود، مسیر با `429 RATE_LIMIT_EXCEEDED` پاسخ می‌دهد. اگر کد به دلیل خطای تحویل قابل ارسال نباشد، `502 MAIL_NOT_SENT` مستند شده است. این موارد باید جداگانه بررسی شوند: محدودیت نرخ با انتظار برطرف میشود، خطای ایمیل به آدرس قابلدسترس و تحویل عملکردی نیاز دارد. اسرار یا دادههای داخلی سرور ایمیل نباید در پیام خطا قرار گیرند. مورد موفقیت به‌صورت زنده با یک `verification_id` واقعی تأیید شد. پیام مربوطه از طریق یک سرور SMTP جعلی اختصاصی دریافت شد و کد شش‌رقمی از محتوای واقعی ایمیل خوانده شد. علاوه بر این، مورد منفی ۴۲۹ پس از فراخوانی‌های مکرر مشاهده شد. دقیقاً همین اثبات قابل ذکر است؛ با این حال، از آن هنوز یک درخواست دسترسی یا فرآیند پرداخت با موفقیت تکمیل‌شده نتیجه نمی‌شود.

Auth & Absicherung

Keine Authentifizierung erforderlich

strictLimiter: 10 درخواست / 15 دقیقه، وابسته به IP.

Rate-Limit: 10 Anfragen pro 15 Minuten (IP-basiert)

Idempotent: Nein

Parameter

email(body, string, erforderlich)— ایمیلی که باید تأیید شود

Beispiel-Request

{"email":"max@example.com"}

Beispiel-Response

{"ok":true,"verification_id":"<UUID>","expires_in_minutes":10,"resend_cooldown_seconds":60}

Fehlercodes

429 RATE_LIMIT_EXCEEDED — درخواستهای بیش از حد به این نقطه پایانی حساس.
502 MAIL_NOT_SENT — کد تأیید ارسال نشد (خطای تحویل ایمیل).

Live-Test-Nachweis

موفقیت (200، verification_id واقعی) به‌صورت زنده تأیید شد؛ ایمیل مرتبط از طریق سرور SMTP جعلی خودمان دریافت شد، کد ۶ رقمی از محتوای واقعی ایمیل استخراج شد. حالت منفی 429 پس از فراخوانی‌های مکرر مشاهده شد.

← فرمهای عمومی