Đặc tả Kỹ thuật API

API Thông báo Email

Phiên bản	1.0
Base URL	https://api.example.com/v1
Hệ thống	Hệ thống Xác thực
Module	EMAIL - Thông báo Email
Ngày tạo	2026-08-05
Tác giả	Nam Nguyen
SRS liên quan	SRS Thông báo Email

Mục lục

1. Tổng quan
2. Định dạng Phản hồi
3. Mã lỗi
4. Giới hạn Tốc độ
5. Endpoints
6. Phân trang
7. Sự kiện Webhook
8. Nhật ký Thay đổi

1. Tổng quan

1.1 Yêu cầu được giải quyết

Yêu cầu SRS	Endpoint API
FR-001 Gửi Email Xác minh	RabbitMQ: verification.email
FR-002 Gửi lại Email Xác minh	RabbitMQ: verification.email
FR-003 Theo dõi Giao Email	POST /api/webhooks/email/delivered
FR-004 Ghi log Sự kiện Email	RabbitMQ: log.events

1.2 Nguyên tắc API

Driving bởi sự kiện qua RabbitMQ để xử lý bất đồng bộ
Callback webhook để theo dõi giao dịch
JSON request/response
Không trạng thái (Xác thực JWT qua Better Auth)

1.3 Xác thực

Các endpoint webhook yêu cầu xác thực chữ ký.

X-Webhook-Signature: HMAC-SHA256 của request body

2. Định dạng Phản hồi

2.1 Phản hồi Thành công

{
  "success": true,
  "data": { ... },
  "meta": {
    "requestId": "req-abc-123",
    "timestamp": "2026-07-24T10:30:00Z"
  }
}

2.2 Phản hồi Lỗi

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Dữ liệu đầu vào không hợp lệ",
    "details": [
      { "field": "email", "message": "Định dạng email không hợp lệ" }
    ]
  }
}

3. Mã lỗi

HTTP Status	Mã lỗi	Mô tả
400	EMAIL_001	Địa chỉ email không hợp lệ
400	EMAIL_002	Không tìm thấy mẫu email
502	EMAIL_003	Lỗi nhà cung cấp - giao email thất bại
429	EMAIL_004	Vượt quá giới hạn tốc độ
401	EMAIL_005	Chữ ký webhook không hợp lệ

4. Giới hạn Tốc độ

Loại Endpoint	Yêu cầu/phút	Burst
Endpoint webhook	100	50
Gửi email (mỗi người dùng)	5	2

5. Endpoints

5.1 Endpoint Webhook

POST /api/webhooks/email/delivered FR-003

Nhận callback trạng thái giao email từ nhà cung cấp email.

Yêu cầu:

{
  "verification_id": "string (bắt buộc)",
  "status": "delivered | failed (bắt buộc)",
  "provider_message_id": "string (bắt buộc)",
  "error_message": "string | null (tùy chọn)"
}

Phản hồi 200:

{
  "success": true,
  "message": "Webhook đã được xử lý"
}

Phản hồi 400:

{
  "success": false,
  "error": "Payload webhook không hợp lệ"
}

6. Phân trang

Tất cả endpoint danh sách hỗ trợ phân trang offset.

GET /email/logs?page=2&limit=20

7. Sự kiện Webhook

7.1 Hàng đợi RabbitMQ

verification.email

Hàng đợi cho yêu cầu xác minh email từ module AUTH.

Sự kiện	Người gửi	Mô tả
verification.email.requested	AUTH	Người dùng yêu cầu xác minh email
verification.email.resent	AUTH	Người dùng gửi lại xác minh email

Định dạng Tin nhắn

{
  "user_id": "uuid",
  "email": "string",
  "channel": "email",
  "otp": "string",
  "verification_id": "string"
}

log.events

Hàng đợi để gửi sự kiện giao email đến module Logger.

Sự kiện	Người gửi	Mô tả
email.event.logged	EMAIL	Sự kiện giao email (đã gửi, đã giao, thất bại)

8. Nhật ký Thay đổi

Ngày	Phiên bản	Thay đổi
2026-07-24	1.0.0	Phát hành ban đầu