ESIM/EsimLao/docs/api_auth_otp.txt

# EsimLao Authentication API Documentation

## Overview
API xác thực người dùng qua email với OTP (One-Time Password).
URL_UAT : http://149.28.132.56:8360/
---

## 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
```json
{
    "email": "user@example.com",
    "lang": "lo"  // Default: "lo" / en
}
```

### 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)
```json
{
    "code": 0,
    "message": "<Config: OTP_SENT_SUCCESS>",
    "data": {
        "email": "user@example.com",
        "expireInSeconds": 300
    }
}
```

### Response Error (200)
```json
// Email không được cung cấp
{
    "code": -801,
    "message": "<Config: EMAIL_REQUIRED>",
    "data": {}
}

// Lỗi hệ thống
{
    "code": -6,
    "message": "<Config: SYSTEM_FAILURE>",
    "data": {}
}
```

### Response Fields
| Field | Type | Description |
|-------|------|-------------|
| code | int | 0 = Success, khác 0 = Error (xem Error Codes) |
| message | string | Thông báo từ CONFIG table (theo ngôn ngữ) |
| 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
```json
{
    "email": "user@example.com",
    "otpCode": "123456",
    "lang": "lo"  // Default: "lo" / en
}
```

### Parameters
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| email | string | Yes | - | Email đã nhận OTP |
| otpCode | string | Yes | - | Mã OTP 6 số |
| lang | string | No | "lo" | Ngôn ngữ thông báo: `lo` (ລາວ), `en` (English) |

### Response Success (200)
```json
{
    "code": 0,
    "message": "<Config: LOGIN_SUCCESS>",
    "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
```json
// Thiếu email hoặc OTP
{
    "code": -801,
    "message": "<Config: EMAIL_OTP_REQUIRED>",
    "data": {}
}

// OTP không hợp lệ
{
    "code": -201,
    "message": "<Config: OTP_INVALID>",
    "data": {}
}

// OTP đã được sử dụng
{
    "code": -203,
    "message": "<Config: OTP_ALREADY_USED>",
    "data": {}
}

// OTP đã hết hạn
{
    "code": -202,
    "message": "<Config: OTP_EXPIRED>",
    "data": {}
}

// Không tìm thấy người dùng
{
    "code": -300,
    "message": "<Config: USER_NOT_FOUND>",
    "data": {}
}

// Lỗi hệ thống
{
    "code": -6,
    "message": "<Config: SYSTEM_FAILURE>",
    "data": {}
}
```

### Response Fields
| Field | Type | Description |
|-------|------|-------------|
| code | int | 0 = Success, khác 0 = Error (xem Error Codes) |
| message | string | Thông báo từ CONFIG table (theo ngôn ngữ) |
| 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
```bash
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
```bash
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
```bash
curl -X GET https://api.esimlao.com/apis/user/profile \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```