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

向指定邮箱发送一个 6 位、有效期 10 分钟的确认代码——此为访问申请的第一步。

`POST /api/public/access-request/email/start-verification` 为公开访问申请启动电子邮件验证。该请求无需登录,并在 Body 字段 `email` 中包含待验证的地址。处理成功后,系统会发送一个六位数的确认码,有效期为十分钟。 响应包含 `ok`、`verification_id`、`expires_in_minutes` 和 `resend_cooldown_seconds`。在随后的验证(Verify)路由中,必须将 `verification_id` 与同一电子邮件地址及收到的确认码一起使用。它不是登录令牌,不得作为永久用户标识存储或公开记录。 该端点不是幂等的。多次成功调用可能会产生多个验证流程或新的确认码。因此,适用基于 IP 的严格限制:15 分钟内最多十次请求。此外,响应还会提示 60 秒的重发锁定。在此期间,界面不应触发重新发送,并应清楚地显示剩余等待时间。 如果超出限制,该路由将返回 `429 RATE_LIMIT_EXCEEDED`。如果因投递错误而无法发送确认码,则文档记录的结果为 `502 MAIL_NOT_SENT`。这些情况需分别处理:速率限制可通过等待解决,邮件错误则需要一个可送达的地址和正常运行的投递。错误消息中不得包含机密或内部邮件服务器数据。 成功情况已使用真实的 `verification_id` 进行了实时验证。相关消息通过自有的 Fake-SMTP 服务器接收,六位数确认码从真实的电子邮件内容中读取。此外,还观察到了多次调用后的 429 负面情况。可以提及的正是这一证明;但这并不意味着访问申请或支付流程已成功完成。

身份验证与安全

无需身份验证

strictLimiter:10 次请求/15 分钟,绑定 IP。

速率限制: 10 Anfragen pro 15 Minuten (IP-basiert)

幂等: 否

参数

email(body, string,必填)— 待验证的电子邮件地址

请求示例

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

响应示例

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

错误代码

429 RATE_LIMIT_EXCEEDED — 对该敏感端点的请求过多。
502 MAIL_NOT_SENT — 无法发送确认代码(邮件投递失败)。

实时测试证明

成功(200,真实 verification_id)已实时验证;相关邮件由自有的模拟 SMTP 服务器接收,6 位验证码取自真实邮件内容。多次调用后观察到失败场景 429。

← 公共表单