ESIM/EsimLao/docs/api_auth_otp.md

EsimLao Authentication API Documentation

Overview

API xác thực người dùng qua email với OTP (One-Time Password).

---

1. Request OTP

Gửi mã OTP đến email người dùng để xác thực đăng nhập.

Endpoint

POST /apis/auth/request-otp

Request Headers

Header	Value	Required
Content-Type	application/json	Yes

Request Body

{
    "email": "user@example.com",
    "lang": "vi"
}

Parameters

Field	Type	Required	Default	Description
email	string	Yes	-	Email address của người dùng
lang	string	No	"vi"	Ngôn ngữ email: vi (Tiếng Việt), en (English), lo (ລາວ)

Response Success (200)

{
    "code": 0,
    "message": "OTP sent successfully",
    "data": {
        "email": "user@example.com",
        "expireInSeconds": 300
    }
}

Response Error (200)

{
    "code": 1,
    "message": "Email is required",
    "data": {}
}

Response Fields

Field	Type	Description
code	int	0 = Success, khác 0 = Error
message	string	Thông báo kết quả
data.email	string	Email đã gửi OTP
data.expireInSeconds	int	Thời gian OTP hết hạn (giây)

Notes

• OTP gồm 6 chữ số
• OTP có hiệu lực trong 5 phút
• Mỗi lần request mới sẽ hủy các OTP cũ chưa sử dụng
• Nếu email chưa tồn tại, hệ thống tự động tạo tài khoản mới

---

2. Verify OTP

Xác thực mã OTP và hoàn tất đăng nhập.

Endpoint

POST /apis/auth/verify-otp

Request Headers

Header	Value	Required
Content-Type	application/json	Yes

Request Body

{
    "email": "user@example.com",
    "otpCode": "123456"
}

Parameters

Field	Type	Required	Description
email	string	Yes	Email đã nhận OTP
otpCode	string	Yes	Mã OTP 6 số

Response Success (200)

{
    "code": 0,
    "message": "Login successful",
    "data": {
        "userId": 12345,
        "email": "user@example.com",
        "fullName": "Nguyen Van A",
        "avatarUrl": "https://example.com/avatar.jpg",
        "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
        "expiresAt": "2024-12-30T10:00:00Z"
    }
}

Response Error Cases

// OTP không hợp lệ
{
    "code": 1,
    "message": "Invalid OTP",
    "data": {}
}

// OTP đã được sử dụng
{
    "code": 1,
    "message": "OTP has already been used",
    "data": {}
}

// OTP đã hết hạn
{
    "code": 1,
    "message": "OTP has expired",
    "data": {}
}

Response Fields

Field	Type	Description
code	int	0 = Success, khác 0 = Error
message	string	Thông báo kết quả
data.userId	int	ID người dùng
data.email	string	Email người dùng
data.fullName	string	Họ tên đầy đủ
data.avatarUrl	string	URL ảnh đại diện (nullable)
data.accessToken	string	JWT access token
data.refreshToken	string	Refresh token để làm mới access token
data.expiresAt	datetime	Thời điểm access token hết hạn

Notes

• Access token có hiệu lực 24 giờ
• Refresh token có hiệu lực 30 ngày
• Mỗi lần đăng nhập thành công, các token cũ sẽ bị thu hồi

---

Error Codes

Success

Code	Constant	Description
0	Success	Thành công (mọi request thành công đều trả về 0)

General Errors (-1 to -99)

Code	Constant	Description
-1	Error	Lỗi chung
-6	SystemError	Lỗi hệ thống

OTP Errors (-200 to -299)

Code	Constant	Description
-200	OtpRequired	Yêu cầu OTP
-201	OtpInvalid	OTP không hợp lệ
-202	OtpExpired	OTP đã hết hạn
-203	OtpAlreadyUsed	OTP đã được sử dụng
-204	OtpMaxAttemptsExceeded	Vượt quá số lần thử
-205	OtpSendFailed	Gửi OTP thất bại
-206	OtpTooManyRequests	Request quá nhiều

User Errors (-300 to -399)

Code	Constant	Description
-300	UserNotFound	Không tìm thấy người dùng
-304	InvalidEmail	Email không hợp lệ

Validation Errors (-800 to -899)

Code	Constant	Description
-801	RequiredFieldMissing	Thiếu trường bắt buộc

---

Authentication

Sau khi đăng nhập thành công, sử dụng accessToken trong header cho các API yêu cầu xác thực:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

---

Flow Diagram

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Client    │     │   API       │     │   Email     │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │
       │ POST /request-otp │                   │
       │──────────────────>│                   │
       │                   │                   │
       │                   │ Generate OTP      │
       │                   │ Save to DB        │
       │                   │ Queue Email       │
       │                   │                   │
       │    Response       │                   │
       │<──────────────────│                   │
       │                   │                   │
       │                   │  Send OTP Email   │
       │                   │──────────────────>│
       │                   │                   │
       │                   │                   │ OTP Email
       │<──────────────────────────────────────│
       │                   │                   │
       │ POST /verify-otp  │                   │
       │──────────────────>│                   │
       │                   │                   │
       │                   │ Verify OTP        │
       │                   │ Generate JWT      │
       │                   │                   │
       │ Token Response    │                   │
       │<──────────────────│                   │
       │                   │                   │

---

Example Usage (cURL)

Request OTP

curl -X POST https://api.esimlao.com/apis/auth/request-otp \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "lang": "vi"
  }'

Verify OTP

curl -X POST https://api.esimlao.com/apis/auth/verify-otp \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "otpCode": "123456"
  }'

Use Token

curl -X GET https://api.esimlao.com/apis/user/profile \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."