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

Magpadala ng isang 6-digit na code ng pagpapatunay na may bisa sa loob ng 10 minuto sa tinukoy na email address — ito ang unang hakbang bago mag-apply para sa access.

`POST /api/public/access-request/email/start-verification` ay nagsisimula ng proseso ng pag-verify ng email para sa isang kahilingan ng pampublikong pag-access. Ang kahilingan ay hindi nangangailangan ng pag-login at naglalaman ng address na dapat i-verify sa loob ng field na `email`. Kapag matagumpay ang pagproseso, nagpapadala ang sistema ng isang anim na digit na code ng pagpapatunay na may bisa sa loob ng sampung minuto. Ang tugon ay naglalaman ng `ok`, isang `verification_id`, `expires_in_minutes`, at `resend_cooldown_seconds`. Ang `verification_id` ay dapat gamitin kasama ng parehong email address at ang natanggap na code sa susunod na ruta ng pag-verify. Ito ay hindi isang login token at hindi dapat i-save bilang permanenteng identifier ng gumagamit o ilantad sa publiko. Ang endpoint na ito ay hindi idempotent. Ang maraming matagumpay na pagtawag ay maaaring magresulta sa maraming proseso ng pag-verify o mga bagong code. Dahil dito, mayroong mahigpit na limitasyon batay sa IP address na sampung kahilingan sa loob ng 15 minuto. Bukod pa rito, ang tugon ay nagpapahiwatig ng isang pagkaantala ng 60 segundo. Sa panahong ito, ang interface ay hindi dapat mag-trigger ng muling pagpapadala at dapat ipakita nang malinaw ang natitirang oras ng paghihintay. Kung nalampasan ang limitasyon, ang ruta ay tumutugon gamit ang `429 RATE_LIMIT_EXCEEDED`. Kung hindi maipadala ang code dahil sa isang error sa paghahatid, ang `502 MAIL_NOT_SENT` ay naitala. Ang mga kasong ito ay dapat tratuhin nang hiwalay: Ang isang limitasyon ng rate ay nalulutas sa pamamagitan ng paghihintay, habang ang isang error sa email ay nangangailangan ng isang maaasahang address at isang gumaganang paghahatid. Ang mga lihim o panloob na data ng server ng email ay hindi dapat isama sa mensahe ng error. Ang matagumpay na kaso ay na-verify nang live gamit ang isang tunay na `verification_id`. Ang kaugnay na mensahe ay natanggap sa pamamagitan ng isang sariling pekeng SMTP server, at ang anim na digit na code ay nabasa mula sa aktwal na nilalaman ng email. Bukod pa rito, ang negatibong kaso ng 429 ay naobserbahan pagkatapos ng paulit-ulit na mga pagtawag. Ang partikular na katibayan na ito ay maaaring banggitin; gayunpaman, hindi ito nangangahulugan ng isang matagumpay na nakumpletong kahilingan ng pag-access o proseso ng pagbabayad.

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

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