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

Lähettää 6-numeroisen vahvistuskoodin, joka on voimassa 10 minuuttia, annettuun sähköpostiosoitteeseen – tämä on ensimmäinen vaihe pääsyn hakemisen yhteydessä.

`POST /api/public/access-request/email/start-verification` käynnistää sähköpostin vahvistusprosessin julkisen pääsyn pyynnön yhteydessä. Pyyntö ei vaadi kirjautumista, ja tarkistettava osoite on määritelty `email`-kentässä. Onnistuneen käsittelyn jälkeen järjestelmä lähettää kuusi numeroa sisältävän vahvistuskoodin, joka on voimassa kymmenen minuuttia. Vastauksessa on `ok`, `verification_id`, `expires_in_minutes` ja `resend_cooldown_seconds`. `verification_id`-tunnus on käytettävä yhdessä saman sähköpostiosoitteen ja vastaanotetun koodin kanssa seuraavassa vahvistusvaiheessa. Se ei ole kirjautumistunnus, eikä sitä saa tallentaa pysyväksi käyttäjätunnukseksi tai julkaista lokitiedostoissa. Päätepiste ei ole idempotentti. Useat onnistuneet pyynnöt voivat käynnistää useita vahvistusprosesseja tai tuottaa uusia koodeja. Siksi IP-osoitteen perusteella on käytössä tiukka rajoitus: enintään kymmenen pyyntöä 15 minuutin aikana. Lisäksi vastaus sisältää tiedon 60 sekunnin uudelleenlähetysrajoituksesta. Käyttöliittymän ei pitäisi käynnistää uutta lähetystä tämän aikana, ja jäljellä oleva odotusaika on näytettävä selkeästi. Jos rajoitus ylittyy, päätepiste palauttaa `429 RATE_LIMIT_EXCEEDED`-virheen. Jos koodia ei voida lähettää toimitusvirheen vuoksi, `502 MAIL_NOT_SENT`-virhe on dokumentoitu. Näitä tapauksia on käsiteltävä erikseen: rajoitus ylittyy odottamalla, ja sähköpostivirhe vaatii toimivan sähköpostiosoitteen ja toimituskanavan. Salaisuuksia tai sisäisiä sähköpostipalvelintietoja ei saa sisällyttää virheilmoitukseen. Onnistunut tapaus on validoitu käytännössä oikealla `verification_id`-tunnuksella. Liittyvä viesti vastaanotettiin omalla väärennetyllä SMTP-palvelimella, ja kuusi numeroa sisältävä koodi luettiin oikeasta sähköpostisisällöstä. Lisäksi 429-virhe (rajoitus ylittynyt) havaittiin toistuvien pyyntöjen jälkeen. Juuri tämä havainto voidaan mainita; se ei kuitenkaan tarkoita, että pääsyn pyyntö tai maksuprosessi on onnistunut.

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

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