Khôi phục tài khoản
Quy trình khôi phục mật khẩu bao gồm khởi tạo xác thực và cập nhật mật khẩu mới.
1. Khởi tạo khôi phục mật khẩu
Gửi mã xác thực OTP đến email người dùng để bắt đầu quy trình khôi phục mật khẩu. Mã OTP gồm 6 chữ số và có hiệu lực trong 5 phút (date_expired).
Để không lộ email nào đã có tài khoản, response luôn giống nhau dù email có tài khoản hay không (cùng HTTP 200, cùng các trường, full_name luôn rỗng). Email chỉ được gửi khi có tài khoản; với email chưa có tài khoản, mọi mã OTP nhập vào đều bị từ chối error_otp_invalid. Nhập sai OTP 5 lần thì passport bị huỷ (error_passport_otp_not_found), phải gọi lại recoveryinit.
Endpoint
POST /v1/users/recoveryinit
Body Parameters
| Tên | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
email | string | Có | Email người dùng |
Response Schema
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"passport_id": "8c6600c3-...",
"full_name": "",
"email": "[email protected]",
"otp_length": 6,
"date_created": 1640995200,
"date_expired": 1640995500,
"metadata": {
"action": "recovery"
}
}2. Hoàn tất khôi phục mật khẩu
Xác thực OTP và thiết lập mật khẩu mới cho tài khoản.
Endpoint
POST /v1/users/recoveryfinish
Body Parameters
| Tên | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
email | string | Có | Email người dùng |
password | string | Có | Mật khẩu mới (tối thiểu 8 ký tự) |
otp | string | Có | Mã OTP nhận được qua email |
passport_id | string | Có | ID passport nhận được từ bước Init |
Response Schema
Trả về object User của người dùng đã được cập nhật mật khẩu.
Error Codes
| HTTP | Code | Mô tả |
|---|---|---|
| 422 | error_email_required | Thiếu email |
| 422 | error_email_invalid | Định dạng email không hợp lệ |
| 422 | error_password_length_invalid | Mật khẩu quá ngắn |
| 422 | error_passport_id_required | Thiếu ID passport |
| 422 | error_otp_required | Thiếu mã OTP |
| 422 | error_passport_otp_not_found | OTP đã hết hạn, không tồn tại hoặc đã bị huỷ do nhập sai quá 5 lần |
| 422 | error_otp_invalid | Mã OTP không chính xác (kể cả khi email chưa có tài khoản) |
| 500 | error_save_passport | Lỗi lưu trữ thông tin xác thực |
| 500 | error_update_password | Lỗi khi cập nhật mật khẩu mới |