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

دی گئی ای میل ایڈریس پر 6 ہندسوں کا تصدیقی کوڈ بھیجتا ہے جو 10 منٹ تک درست رہتا ہے — رسائی کی درخواست سے پہلے کا پہلا مرحلہ۔

`POST /api/public/access-request/email/start-verification` کسی عوامی رسائی کی درخواست کے لیے ای میل کی تصدیق شروع کرتا ہے۔ اس Request کے لیے لاگ ان ضروری نہیں اور اس میں جانچا جانے والا پتہ Body فیلڈ `email` میں ہوتا ہے۔ کامیاب پراسیسنگ پر نظام چھ ہندسوں کا تصدیقی کوڈ بھیجتا ہے جو دس منٹ کے لیے درست ہوتا ہے۔ Response میں `ok`، ایک `verification_id`، `expires_in_minutes` اور `resend_cooldown_seconds` شامل ہوتے ہیں۔ `verification_id` کو اسی ای میل پتے اور موصول شدہ کوڈ کے ساتھ بعد والے Verify راستے میں استعمال کرنا ضروری ہے۔ یہ لاگ ان ٹوکن نہیں ہے اور اسے مستقل صارف شناخت کے طور پر محفوظ یا عوامی طور پر لاگ نہیں کیا جانا چاہیے۔ یہ اینڈ پوائنٹ idempotent نہیں ہے۔ متعدد کامیاب کالز متعدد تصدیقی عمل یا نئے کوڈز پیدا کر سکتی ہیں۔ اسی لیے IP کی بنیاد پر 15 منٹ میں دس درخواستوں کی سخت حد لاگو ہے۔ اس کے علاوہ جواب 60 سیکنڈ کی دوبارہ بھیجنے کی پابندی کی نشاندہی کرتا ہے۔ اس دوران انٹرفیس کو دوبارہ بھیجنا شروع نہیں کرنا چاہیے اور باقی انتظار کا وقت واضح طور پر دکھانا چاہیے۔ حد سے تجاوز کی صورت میں راستہ `429 RATE_LIMIT_EXCEEDED` کے ساتھ جواب دیتا ہے۔ اگر ترسیل کی خرابی کی وجہ سے کوڈ نہ بھیجا جا سکے تو `502 MAIL_NOT_SENT` دستاویزی ہے۔ ان صورتوں کو الگ الگ سنبھالنا چاہیے: Rate-Limit انتظار سے حل ہوتی ہے، جبکہ میل کی خرابی کے لیے قابلِ رسائی پتہ اور درست کام کرتی ترسیل درکار ہے۔ راز یا اندرونی میل سرور کا ڈیٹا خرابی کے پیغام میں شامل نہیں ہونا چاہیے۔ کامیابی کی صورت کی لائیو تصدیق ایک حقیقی `verification_id` کے ساتھ کی گئی۔ متعلقہ پیغام ایک اپنے Fake-SMTP سرور کے ذریعے وصول کیا گیا اور چھ ہندسوں کا کوڈ حقیقی ای میل کے مواد سے پڑھا گیا۔ اس کے علاوہ بار بار کالز کے بعد 429 کی منفی صورت کا مشاہدہ کیا گیا۔ صرف اسی ثبوت کا ذکر کیا جا سکتا ہے؛ اس سے کسی رسائی کی درخواست یا ادائیگی کے عمل کا کامیابی سے مکمل ہونا ثابت نہیں ہوتا۔

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

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